Prodigi MCP by usefulapi

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

Annotations already cover readOnlyHint/openWorldHint/destructiveHint, but the description adds the crucial non-obvious point that a POST endpoint is nevertheless side-effect free, plus per-method vs all-method shipping behavior, account-currency defaulting, and the CreatedWithIssues outcome for problematic items. The CreatedWithIssues disclosure comes close to return-value detail the missing output schema would normally carry, which is genuinely valuable.

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 most important constraint (pricing only, no charge) and dense with specifics. The second sentence is long and runs several requirements together, which slightly hurts scanability, but no sentence is 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 does real work by enumerating returned cost components and the CreatedWithIssues failure mode, and it clarifies required item fields. It remains silent on things like rate limits or whether quotes expire, which for a pricing endpoint an agent might reasonably want.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces item composition ('sku, copies and the print areas', 'books take pageCount') and the omit-to-get-all-shipping behavior, but the latter is already stated in the schema's shipping_method description, so incremental value is modest.

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 ('Price a print order') and immediately scopes it against the obvious trap — it does not create or charge anything. The enumeration of what the quote contains (item cost, shipping, inserts, tax, total, carrier, lab, unit costs) makes the output shape unambiguous and distinguishes it from the order/product 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?

Clear context: use this to obtain pricing without side effects, and the POST /quotes note plus 'nothing is saved or billed' tells the agent when this is the right call versus creating an order. It stops short of naming an explicit alternative or exclusion (e.g. 'do not use for final order totals — use prodigi_get_order'), so not a 5.

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

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

The annotations already declare this as a read-only, non-destructive, open-world operation, and the description adds useful return-content details: status, per-step details, issues, charges, shipments, recipient, items, metadata. It also discloses the non-obvious behavior that callbackUrl is reduced to its host. It does not cover error or not-found behavior, so it falls short of full behavioral transparency.

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

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

The description is front-loaded with the resource and lookup key, then packs the response payload summary efficiently into a single field list. The final GET endpoint is short and the whole definition has 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-resource read tool with one fully documented parameter and no output schema, the description is largely complete because it summarizes the returned order data and notes callbackUrl redaction. The main omission is usage context relative to sibling tools, but the retrieval contract itself is well covered.

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 schema has 100% description coverage and already documents order_id with an example. The description reinforces that the id is a Prodigi order id but adds no format, lookup, or edge-case semantics beyond the schema. A baseline 3 is appropriate.

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

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

The description clearly states that it retrieves a single print order by Prodigi order id and enumerates the returned data categories. This distinguishes it implicitly from list operations, but it does not explicitly name sibling tools such as prodigi_list_orders or prodigi_get_order_actions.

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 'One print order by Prodigi order id,' which suggests calling it when a specific order id is already known. However, it gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as list_orders for discovering ids or get_order_actions for action history.

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 useful behavioral context beyond that: it names the action categories checked and describes the returned isAvailable Yes/No field, which matters because there is no output schema.

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

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

The description is two tight sentences plus the endpoint. It front-loads the core capability and immediately clarifies that the tool is non-mutating, with no wasted 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 availability lookup, the description gives enough: what is checked, that it is read-only, the returned availability signal, and the underlying endpoint. An agent has what it needs to invoke and interpret the tool correctly.

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

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

There is only one parameter, order_id, and the input schema has 100% description coverage with an example. The description does not add further parameter semantics beyond the endpoint path, so the baseline of 3 is appropriate.

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

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

The description states a specific resource-scoped operation: checking which order changes Prodigi still allows. It enumerates the action types (cancel, recipient details, shipping method, metadata) and makes clear this is an availability check, not a mutation, which distinguishes it from sibling tools like get_order and list_orders.

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

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

Usage context is clear: call this to learn what changes are currently permitted on an order. The explicit note that it only reports availability and changes nothing helps an agent choose it over a mutation path, though no sibling tool is named as an alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds the concrete endpoint (GET /products/{sku}) and a detailed inventory of the response contents, which is the main behavioral unknown for a read tool. It omits what happens for an unknown SKU and any rate-limit behavior, so it stops short of 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?

Front-loaded with the subject and its return contents, followed by the use case and endpoint; every clause carries information. The field enumeration is long but each item (required print areas, shipping countries, pixel sizes) is genuinely decision-relevant for building quotes.

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 thoroughly across attributes, print areas, and variants. A one-parameter read tool needs nothing more; the only minor omission is error behavior for an invalid SKU.

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

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

There is only one parameter and schema coverage is 100% — the schema already documents sku with an example (GLOBAL-CAN-10x10). The description only restates 'by SKU' without adding format, casing, or lookup-failure semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('Details of one Prodigi product by SKU') and enumerates exactly what is returned: description, dimensions, attributes and allowed values, print areas with required flags, and variants with shipping countries and pixel sizes. The single-item-by-SKU scope clearly distinguishes it from siblings like prodigi_list_orders or prodigi_create_quote.

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

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

'Use it to build valid quote requests' gives a concrete downstream purpose and implicitly points at prodigi_create_quote as the follow-on tool. It does not state when not to use it or how it relates to prodigi_get_spine_width, which could also feed quote construction, so it falls short of full alternative routing.

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 readOnly/destructive/openWorld, but the description adds genuinely useful context by pre-empting the surprise that a 'POST /products/spine' call has no side effects ('nothing is created or charged'). It doesn't cover error behavior for invalid SKUs, but for a pure calculation the safety profile is fully addressed.

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 unit (mm) and purpose front-loaded, followed by the no-side-effects reassurance. The endpoint path is mildly redundant but is what makes the 'pure calculation' claim concrete.

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 4-parameter calculation tool with no output schema, the description supplies the return unit (mm) and the value returned (spine width), which is the key missing piece. Only edge-case behavior (invalid SKU, out-of-range page counts) is left unaddressed.

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

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

Schema description coverage is 100%, so each parameter is already documented; the description only reinforces the relationship between number_of_pages and the returned width. It says nothing extra about sku, destination_country_code, or state, 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 ('Calculate the spine width in mm of a book product') plus the input that drives it (page count) and the use case (cover artwork). An agent can distinguish this from prodigi_create_quote or prodigi_get_product without opening any 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?

'for a page count (for cover artwork)' gives clear context for when to reach for this tool, and 'nothing is created or charged' implicitly routes the agent away from quote/order tools for what is a look-up. No explicit named alternative or exclusion, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuine value beyond that with the sort order, the returned field set, the pagination contract (has_more/next_skip), and a PII warning that recipient names and addresses are real customer data. It omits auth/rate-limit behavior, keeping it short of a 5.

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

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

Four dense sentences, front-loaded with purpose and sort order, followed by filters, paging, and the privacy note. Every sentence carries an agent-relevant fact and nothing is repeated from the schema verbatim.

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 and the has_more/next_skip envelope, which is the critical piece for correct iteration. Only auth/error behavior is left unaddressed, which is minor for a read-only list 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 every parameter (top, skip, status, order_ids, created_from/to, merchant_references) is already documented with constraints and defaults. The description restates the paging and filter semantics at a high level without adding syntax or format details 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?

Specific verb+resource ('List print orders of this Prodigi account') plus scope details: sort order, the fields included (status stage, items, shipments, charges), and the underlying endpoint. It is clearly distinguishable from the sibling prodigi_get_order, which fetches a single order.

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

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

Explains the filtering contexts (status, creation time, order ids, merchant references) and the paging contract, which tells the agent when this tool is the right choice over single-order retrieval. It stops short of explicitly naming alternatives or exclusions.

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