FinerWorks MCP by usefulapi

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the exclusions — API keys, payment profile, and third-party connection secrets are never returned — which prevents an agent from calling it expecting secret material, plus the underlying endpoint for traceability.

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 what is returned, followed by the security boundary and the endpoint. No filler, and the most decision-relevant constraint (secrets excluded) arrives early.

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 return values — and it does so by enumerating the returned fields and the excluded ones. Only the exact shapes of nested items (billing vs. business address, app details) are left unspecified, a minor gap for a zero-parameter 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?

The tool takes zero parameters, so the baseline is 4; there is nothing to disambiguate. The description correctly conveys that no identifiers are needed because the account is resolved from the API keys themselves.

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 (the FinerWorks account tied to the API keys) and enumerates exactly which attributes are returned: username, email, addresses, credits, shipping preferences, app details. That field-level enumeration makes it unambiguous against siblings like get_order or get_product_details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent infers it should call this when it needs account/credential context rather than order or product data. The endpoint path 'GET /v3/test_my_credentials' hints at a credential-validation use case, but the description never explicitly says when to prefer this over alternatives or what prerequisites exist.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the endpoint 'POST /v3/frame_details' and id provenance, but does not describe return behavior, authentication needs, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is very short and front-loaded with the core purpose. The parenthetical provenance and endpoint are compact, and there is no filler or redundant 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?

For a simple one-parameter read-only getter with full schema coverage and clear annotations, the description provides enough context to select and invoke the tool correctly. It could say more about what frame details are returned, but that is a minor gap for this complexity level.

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 id parameter itself is fully documented by the schema. The description adds useful meaning by indicating that the id comes from finerworks_list_frame_collections, guiding the agent on how to obtain a valid value.

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 resource and access pattern: one frame retrieved by id. It also identifies finerworks_list_frame_collections as the source of the id, which helps distinguish it from list-style siblings, though it does not explicitly contrast with all other get_* 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?

The parenthetical '(from finerworks_list_frame_collections)' implies the intended workflow: call the list tool first, then fetch details using one of its ids. However, it does not state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true. The description adds meaningful context beyond them: the retrieval requires a second identity factor (the email on the order), which signals a lookup that can fail on mismatch, plus the underlying endpoint. It stops short of describing error behavior or output shape.

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, zero waste, with the return contents and required inputs front-loaded. Nothing is padded and 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 what comes back (items, recipient, shipping, status, totals) so the agent knows what this call yields. The only remaining gap is failure behavior when the email does not match the 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 coverage is 100% and both parameters carry their own descriptions, so the schema does the heavy lifting. The description's 'order GUID and the email address' merely restates the required fields without adding format, matching rules, or which of billing/recipient email is accepted.

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 ('One order in full') and enumerates the returned facets: items, recipient, shipping method, status and totals. An agent can distinguish it from the narrower finerworks_get_order_status, 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?

Gives the prerequisite ('Needs the order GUID and the email address on the order'), which tells the agent what must be in hand. It does not say when to prefer this over finerworks_get_order_status or finerworks_list_orders, leaving alternative selection 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 cover read-only/non-destructive/open-world, so the description's added value is the not-found contract ('returns nothing') and the fact that both identifier types are accepted — real behavioral context an agent can't get from annotations. It stops short of describing the response shape or any rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences, front-loaded with the purpose and ending with the not-found edge case. The trailing endpoint path is marginally redundant for an agent but small; nothing else 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?

For a 2-optional-param read tool with no output schema and annotations covering the safety profile, the description covers purpose, inputs, and the not-found case. The only gap is not pointing at finerworks_list_order_status_definitions for interpreting the returned status values.

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 both parameters already carry descriptions including the 'Not needed when order_pos is given' note, so the schema does the heavy lifting. The description's phrasing reinforces the either/or lookup but adds no format or constraint detail (e.g. the 50-item cap).

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 ('current production status of orders') with example values ('in production, shipped, ...') and names the two lookup keys. It is clearly distinguishable from siblings like finerworks_get_order (full order) and finerworks_list_order_status_definitions (definitions, not per-order state).

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 ('looked up by your order PO numbers or FinerWorks order ids') and notes the not-found behavior, so an agent can infer when it applies. However, it never explicitly contrasts itself with finerworks_get_order or finerworks_list_pending_orders, 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 and destructiveHint=false; the description adds the genuinely useful clarification that despite being a POST, nothing is ordered or billed, which prevents an agent from misreading the verb as a write. It does not cover rate limits or whether prices can be stale, so it falls short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three short sentences: what it returns first, the safety clarification second, the endpoint last. Every sentence carries information and nothing is repeated unnecessarily.

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-only lookup with annotations covering the safety profile and no output schema, the description says enough to call it correctly. A hint about what the 'breakdown' contains would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, including nested sku/quantity descriptions and the 50-item cap, so the baseline is 3. The description restates the batch limit and 'at given quantities' but adds no format guidance (e.g. SKU vs product code selection criteria) beyond what the schema already documents.

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 pair ('price and price breakdown') plus the concrete scope: up to 50 product codes or virtual inventory SKUs at given quantities. It is clearly a pricing lookup rather than an order/product-detail call, though it does not name a sibling to contrast against.

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?

'Nothing is ordered or billed' implies the intended use case of quoting/estimating prices before committing to an order, but the description never states when to prefer this over finerworks_get_product_details or finerworks_get_order, nor any exclusion.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 25-item batch cap and notes the POST endpoint, which usefully signals a read performed via POST, but it says nothing about rate limits, error behavior for invalid SKUs, or partial failures in a batch.

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 key facts front-loaded; nothing pads it out. The trailing 'POST /v3/get_product_details.' largely restates the tool name, though the endpoint mapping has some value.

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 one fully documented parameter and no output schema, the definition covers what is needed to invoke it correctly. 'Details and pricing' hints at the return shape, but the response structure for a batch of up to 25 SKUs 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?

Schema description coverage is 100%, with sku and quantity both explained in-schema. The description only echoes the quantity concept ('at given quantities') and the 25-item limit, adding little beyond the structured fields, 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 details and pricing) against a specific resource (virtual inventory SKUs) with a batching scope of 25. An agent can tell it is a per-SKU lookup tool, though it does not explicitly distinguish itself from sibling finerworks_get_prices or finerworks_list_virtual_inventory.

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 description suggests calling it when you already hold SKUs and quantities, but it never states when to prefer it over finerworks_get_prices (pricing-only) or finerworks_list_virtual_inventory (enumeration). No prerequisites or exclusions are given.

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 largely covered; the description still adds the non-obvious fact that this read is a POST to /v3/list_shipping_options_multiple and that no order or billing occurs. Returned content ('shipping_code values') is disclosed, though error behavior for invalid addresses and any rate limits are not.

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 compact clauses, each doing distinct work: purpose, inputs, return value, side-effect disclaimer, followed by the endpoint. Purpose and safety constraints are front-loaded with zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps up by naming what comes back (shipping_code values), and it clarifies the non-mutating nature of a POST endpoint. It stops short of noting behavior on an invalid/unserviceable address, which is the main remaining gap for a nested-payload quoting 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 description coverage is 100%, so the schema already documents recipient fields, state_code vs province, country_code format and the 1-999 quantity range. The description only restates the two top-level groups at a high level, adding no syntax or validation nuance 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 ('Shipping options and rates'), scopes it precisely ('for one prospective order'), and enumerates the inputs (recipient address plus SKUs and quantities). The phrase 'prospective order' plus 'Nothing is ordered or billed' makes it unmistakable versus list_orders/get_order/pending_orders siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the pre-purchase quoting scenario ('an order would need', 'Nothing is ordered or billed') but never names an alternative such as validate_address for address checking or get_prices for product pricing, nor states prerequisites. Usage is inferable but not spelled out.

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 does add one real behavioral trait not in the structured fields: the result shape changes depending on which parameter is supplied (collections vs. frames). The POST/endpoint note is transport trivia rather than behavior, and nothing is said about result size or pagination.

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 definition and followed immediately by the parameter-driven branch. The trailing 'POST /v3/list_collections' endpoint is not useful for tool selection and slightly dilutes the otherwise tight phrasing.

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 0 required params, 100% schema coverage and no output schema, the main thing an agent needs is to know the response depends on inputs — which the description covers. Missing only secondary details like pagination or how to discover valid collection ids, which are minor for a read-only listing 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 description coverage is 100% and both parameter descriptions already state the exact same semantics ('Required to list the frames inside a collection', 'compatible with this product code'), so the prose largely restates the schema. Baseline 3 applies; no format hints or valid-id discovery guidance are added.

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 the resource ('Frame collections (categories)') and, importantly, a second verb mode: listing frames inside a collection. This is more specific than a bare list tool and distinguishes it from siblings like list_mats or list_glazing, though it never names an alternative tool 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?

'Pass a collection id to list the frames in it; pass a product code to show only collections and frames compatible with that print product' gives concrete conditional usage for each parameter, which is genuinely actionable routing. It stops short of stating when NOT to use it or pointing at get_frame for single-frame lookups.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that glazing comprises glass and acrylic and the underlying endpoint path; it says nothing about filtering behavior when the optional id is supplied or what happens for an unknown id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short sentences, front-loaded with the resource meaning and followed by the endpoint reference. Nothing is padded and the domain hint (glass and acrylic) 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, one-optional-param listing tool with full schema coverage and annotations, this is close to sufficient. The only real gap is that with no output schema the agent cannot know what fields a glazing record exposes (id, name, price), which limits reuse of the result.

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 optional parameter is documented in the schema as 'Only this glazing id.', so the schema carries the semantics. The description never mentions the id filter or what omitting it returns, adding no meaning 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?

The description states the resource precisely — the available glazing (glass and acrylic) options — and the parenthetical clarifies the domain vocabulary. The 'list' verb is implied by the noun phrase rather than stated, and no sibling tool is named, but glazing is a clearly distinct resource from mats, frames, or media types.

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 guidance on when to call this versus other catalog-listing siblings, nor any statement of prerequisites or typical workflow (e.g., call before get_prices to know valid glazing ids). The agent must infer usage entirely from the resource name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The only added behavioral fact is the 'POST /v3/list_mats' endpoint, which is mildly useful (a read performed via POST) but says nothing about pagination, catalog size, or whether the list evolves over time. Most of the burden is left unaddressed.

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 fragments with zero padding, but the terseness tips into under-specification rather than efficiency; there is no front-loaded statement of what the tool returns or how to narrow results.

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, so the description should explain what a 'mat' entry contains and how results are shaped; it does neither. For a list tool with an open-world catalog, an agent is left guessing about the response structure.

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% with a single optional integer 'id' already documented as 'Only this mat id.' The description adds nothing about the filter, which is acceptable given full schema coverage — 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?

Names the resource ('mats' with the clarifying gloss 'matting') and implies a listing, but the description is a noun fragment with no verb — the listing action comes only from the title. It is distinguishable from get_frame or list_media_types by the resource noun, so it avoids confusion with siblings, but barely.

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 statement of when to call this versus siblings like finerworks_get_product_details or finerworks_list_frame_collections, and no mention of when the optional id filter should be used instead of a full listing. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description carries little burden; beyond that it only repeats the HTTP route (POST /v3/list_media_types). It says nothing about whether all media are returned by default, ordering, or volume of results.

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 very short fragments with no filler, but the second fragment is a raw HTTP route that duplicates no information an agent can act on and is not front-loaded with the actual purpose sentence. Terse rather than structured.

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, so the description should indicate what listing yields (media ids, names, papers vs. canvas, whether pricing is included). For a catalog-enumeration tool that an agent will use to resolve valid media ids, this leaves the calling contract underspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single `ids` parameter is fully documented in the schema. The description adds no filter semantics (e.g. that omitting `ids` returns the full catalog), 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?

"The papers and media FinerWorks prints on" identifies the resource (print media) and distinguishes it from sibling lists like list_mats or list_glazing, but it is a noun fragment with no verb — an agent must infer the tool lists/enumerates these. The title supplies "List", but the description alone does not state the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no exclusions, and no pointer to alternatives (e.g. get_product_details for media tied to a product). The agent is left to guess whether this is a catalog lookup or a pricing lookup.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: results are newest-first and arrive via POST /v3/list_orders, which matters because an agent might otherwise assume a GET-style filter tool. It does not discuss pagination limits or cancellation defaults, but those live in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences, zero waste. The resource and sort order come first, filter axes second, and the endpoint reference is tucked at the end where it does not obstruct scanning.

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 nine-parameter, all-optional read tool with no output schema, the description does the important work of naming what is returned (status, totals, dates) and the sort order. Pagination mechanics and the show_cancelled default are left entirely to the schema, which is acceptable but leaves a small gap for an agent iterating 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 coverage is 100%, so the baseline is 3. The description earns a point above baseline by clarifying the ambiguous order_pos parameter, spelling out that it holds the caller's own PO numbers from systems like Shopify or Squarespace, and by framing date_from/date_to as a paired range.

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 submitted print orders) plus ordering and returned fields (status, totals, dates), so the agent knows exactly what comes back. It does not explicitly distinguish itself from siblings like finerworks_list_pending_orders or finerworks_get_order, leaving the read-scope boundary implicit.

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 enumeration of filter axes (free text, status, order ids, POs, date range) implies how to narrow results, but there is no explicit statement of when to use this versus finerworks_list_pending_orders or finerworks_get_order for a single order. Usage is inferable rather than prescribed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the response pairs statuses with ids and that ids are stable references, plus the underlying endpoint. It says nothing about ordering, completeness (are these all statuses or only active ones?), or response shape beyond 'with their ids'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three short clauses with zero filler, and the core purpose is front-loaded before the id-usage hint and the endpoint. Nothing could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless read-only catalog lookup with no output schema, the description is close to sufficient. The one real gap is that the return structure is only hinted at ('with their ids') rather than stated, so an agent cannot predict the field names of each entry.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The note about ids being stable references adds a small amount of semantic value for how the return values should be used.

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+resource: lists all production order statuses with their ids. This is clearly distinguishable from the sibling finerworks_get_order_status (which fetches the status of one order), though the description never names that sibling to make the distinction explicit. An agent can still infer the catalog-vs-instance difference from 'All production statuses an order can have'.

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 the id as the stable reference' gives downstream usage guidance but not tool-selection guidance. There is no explicit statement of when to call this versus finerworks_get_order_status, nor any prerequisite or exclusion. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine business context that pending orders incur no billing, but says nothing about pagination, result limits, or default behavior when no filters are supplied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single tight sentence with the key constraint front-loaded, followed by the endpoint. No redundant restatement 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 could say more about the shape of the returned list (fields, whether all pending orders return when unfiltered), but read-only annotations plus fully documented optional filters make the definition largely sufficient to invoke 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%, so both filter parameters are already documented in the schema. The description adds no syntax, matching semantics, or interaction details beyond what the schema provides, 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 and resource ('Orders saved but held in a pending status') and defines the scope as not-yet-submitted. It implicitly separates this from finerworks_list_orders via the pending-status qualifier, though it never names that sibling outright.

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 pending-only scope hints at when this tool applies, and 'nothing is billed until submitted' confirms the pre-submission window. But it gives no explicit alternative ('use list_orders for submitted orders') and no guidance on combining the ids/skus filters.

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 this read-only, non-destructive, and open-world, so the safety profile is covered. The description adds the endpoint route (POST /v3/list_product_types) — mildly useful since a POST verb might otherwise suggest mutation. It says nothing about result size, ordering, or whether the list is paginated/complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two compact sentences, front-loaded with the substantive content. The trailing endpoint route is arguably low-value to an agent but costs almost nothing.

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-optional-param read tool with annotations and no output schema, the description is adequate but thin: it never indicates the shape of returned items (ids, names, capability flags) that an agent would need to chain into finerworks_get_product_details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'ids' parameter is documented as an optional filter, so the schema does the heavy lifting. The description adds no filtering semantics (e.g., what happens when ids contains unknown or duplicate values) beyond enumerating example type names.

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 the resource concretely ('The product types FinerWorks prints') and grounds it with example values (fine art paper, canvas, wood, metal, cards), so an agent knows exactly what comes back. It does not explicitly distinguish itself from near-neighbors like finerworks_list_media_types or finerworks_list_style_types, which is the only thing separating it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to call this versus finerworks_get_product_details, finerworks_list_media_types, or the other list_* siblings. The only implicit cue is the 'ids' filter, which hints at a lookup-by-id use case but is never stated in prose.

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 useful domain context (these are non-dynamic accessory items) but says nothing about result volume, ordering, or whether an empty ids filter returns everything. The POST endpoint note is informational only.

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, zero padding, and the definition of what the tool returns is front-loaded. The trailing endpoint path is marginally useful metadata rather than wasted space.

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-optional-param list tool with annotations covering safety and a fully documented schema, this is adequate. It does not say what a static product record contains or how the ids filter behaves when multiple ids are supplied, which an agent choosing between this and virtual inventory would benefit from.

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% on the single optional ids parameter, so the schema fully documents it (array, 1-100 items, filter semantics). The description contributes no additional parameter meaning, which is acceptable at full coverage but not value-additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource precisely and defines what makes a product 'static' (non-dynamic, mostly accessories) plus gives the underlying endpoint. It stops short of explicitly contrasting with list_virtual_inventory or get_product_details, but the 'non-dynamic' qualifier does most of the disambiguation work.

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?

'That can be added to an order' implies the usage context (order-building for accessories) but never states when to call this versus the sibling listing tools. No exclusions, no prerequisites, and no alternative named.

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 endpoint path and example values but says nothing about result volume, whether all styles are always returned, or how these types relate to downstream order/product calls.

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 domain concept before the endpoint reference. The endpoint path is arguably redundant for most agents but is compact and harmless.

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 low-complexity read-only list tool with annotations and a fully documented schema, this is minimally sufficient. It stops short of explaining what style types are used for (e.g., selecting a print style when placing an order), which would materially help an agent decide to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional 'ids' parameter is fully documented in the schema, so baseline 3 applies. The description contributes no additional meaning about the filter beyond what the schema already 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+resource ('print styles FinerWorks offers') and gives concrete examples (gallery wrap, float mount) that differentiate it from sibling list tools like list_mats or list_media_types. It does not explicitly name those siblings, but the examples do the disambiguating work implicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to call this versus the other listing tools, no mention that the returned style ids are needed for product/price lookups, and no note that the optional ids filter can narrow results. The agent is left to infer all usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the POST endpoint, but says nothing about pagination behavior, result caps (per_page 50) or rate limits that go beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with no filler: content first, filter capability second, endpoint last. Every clause earns its place and nothing important 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 usefully enumerates the returned fields (title, SKU, product code, image, price), and pagination is fully handled by the schema's page/per_page/next_page docs. Only the lack of guidance versus the static-products sibling keeps it from a 5.

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 individually documented, including defaults and limits. The description's filter list merely restates the schema's skus/search/product_codes/product_type_ids, adding no syntax or interaction detail, 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 ('reusable print products (SKUs) saved in the account's virtual inventory') plus the fields returned, so an agent knows exactly what is listed. It does not name the sibling it is most easily confused with, finerworks_list_static_products, so differentiation is left 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?

'Filter by text, SKU, product code or product type' implies how to narrow results but gives no explicit when-to-use context or exclusions. Nothing tells the agent when to prefer this over finerworks_list_static_products or finerworks_list_product_types.

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; the description usefully reinforces that no state is persisted and that the response is a corrected address. It stops short of saying what happens when the address cannot be corrected (error vs. partial suggestions).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two compact sentences, the side-effect disclaimer front-loaded and the API path last. Nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only validator with annotations covering the safety profile, the key facts (no persistence, returns corrected address) are present. Only the failure/uncorrectable-address behavior is left unaddressed, and there is no output schema to describe the response shape.

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 nested recipient field (state_code, province, country_code, etc.) is documented in the schema, so baseline 3 applies. The description adds nothing about the required nested fields or formats.

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 ('Check a recipient address') and the concrete result ('return FinerWorks' corrected version'), plus the underlying endpoint. No sibling in the list performs address validation, so the resource is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Nothing is saved or ordered' implies this is a pre-flight check to run before creating an order, but the description never says so explicitly and names no alternative or exclusion. Usage is inferable rather than stated.

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