Ordoro MCP by usefulapi

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

Goes beyond the annotations by disclosing that the comment is internal/not sent to the customer, that repeated calls append rather than replace (consistent with idempotentHint=false), and by naming the underlying POST endpoint. No auth/permission or failure-mode detail, so not a 5.

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

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

Two short sentences, front-loaded with a 'WRITE:' signal word, and the API path is compressed to one clause. 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 simple two-parameter append tool with full schema coverage, annotations, and no output schema, the description covers purpose, side effect, and visibility. It stops short of error behavior (e.g., invalid order_number) but nothing essential is missing.

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

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

Schema description coverage is 100% and both parameters are fully documented there, so this is the baseline case. The description's endpoint template adds only marginal syntax context around order_number.

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 ('add an internal comment to an order') and immediately scopes it as team-visible, not customer-facing. Clearly distinct from the read sibling ordoro_list_order_comments.

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?

Implies usage (add a comment to an existing order) but never states when to use this versus looking up comments first, nor any prerequisite like the order needing to exist. The 'Each call adds a new comment' note is the only usage-adjacent guidance.

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 write/idempotent/non-destructive, so the 'WRITE:' prefix is a slight restatement, but the description adds real context beyond them: the tag must pre-exist, the underlying POST endpoint, and that the order's tags are returned.

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

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

One tight sentence, front-loaded with the operation type, followed by a concrete example, the return behavior, and the endpoint. No padding or repetition.

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 notes that the order's tags are returned, and the parameters plus annotations cover the rest. An agent has enough to call it correctly, though error or permission behavior is 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%, so both parameters are already documented including the tag-id source and the order-number prefix format. The description reinforces the tag_id provenance but adds no format or syntax detail beyond the schema, matching the baseline.

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

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

Specific verb (apply) plus resource (an existing order tag) scoped to an order, with the tag-id source named. It clearly distinguishes itself from the sibling ordoro_remove_order_tag and from ordoro_list_order_tags, which it points to for ids.

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 states the precondition that the tag must already exist and be fetched from ordoro_list_order_tags, and gives use cases (put on hold, route). It does not spell out the inverse case versus ordoro_remove_order_tag, but the intent is unambiguous.

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?

readOnlyHint=true is already declared in annotations, so the safety profile is covered by structured data. The description adds real value by enumerating what comes back (lines, addresses, shipping_info, financials, dropship), but says nothing about failure behavior when the order number is unknown, rate limits, 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 front-loaded sentences with no filler: the operation and its scope come first, followed by the returned field groups and the underlying endpoint. Every clause carries information.

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

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

With no output schema, the field enumeration does much of the work an output schema would, and it covers all the meaningful sections. It stops short of describing the response's nested structure or what happens on a missing order, which would fully close the gap for a single-resource get.

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

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

Schema description coverage is 100%, and the schema itself documents the exact format ("1-1001" prefix) and where to obtain the value. The description adds no parameter detail beyond the schema, 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 ("Get one order by order number") and then enumerates the returned fields, which clearly separates it from ordoro_list_orders and the other order siblings. An agent can identify the tool's scope without opening the schema.

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

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

The description implies usage by noting that the order_number comes from ordoro_list_orders, suggesting a list-then-get workflow. However, it gives no explicit when-to-use vs when-not guidance, no mention of the alternatives (e.g., ordoro_get_order_counts or ordoro_list_orders) and no 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?

The readOnlyHint annotation already establishes the safe read-only profile, and the description adds meaningful context by enumerating exactly which statuses are counted and describing the tool as a backlog overview. It does not describe the response shape (e.g., whether zero-count statuses are included) or any rate limits, but with annotations covering safety, this is a solid addition.

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

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

Three short sentences, front-loaded with the core action and the status list, followed by a use-case gloss and the API endpoint. Every element earns its place 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?

For a no-parameter, read-only count tool with no output schema, the description gives enough to understand what is returned (counts per named status) and why it is useful. It stops short of spelling out the exact response object, which is a minor gap given the absence of an output schema.

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

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

There are zero parameters, so the schema-based parameter semantics baseline is 4. The description has no parameters to describe and does not need to compensate for any schema gaps.

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 ('Count') and resource ('orders per status'), and enumerates the statuses. It is clearly distinct from list/get siblings, but the description never names an alternative or states that list_orders cannot produce counts, so sibling differentiation is implicit rather than explicit.

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

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

The phrase 'A quick fulfillment-backlog overview' implies the tool's intended use case, but there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The agent must infer that this is the right tool when a status tally is needed rather than a full order listing.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuine value by disclosing exactly which shipping fields come back, including less obvious ones like return shipment and dropship info. It stops short of noting behavior when no shipment exists (empty vs error) or any rate/permission constraints.

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

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

One front-loaded sentence names the resource and then lists return fields, followed by a short API pointer. The field list is dense but each item is substantive; nothing is padding, though the trailing API-path note adds little for an agent.

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 appropriately carries the return-value burden by enumerating the shipping fields. It is a single-param read-only tool with fully documented schema, so remaining gaps (no-shipment behavior, auth) are minor rather than blocking.

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

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

Schema description coverage is 100%, and the schema fully explains order_number including the sales-channel prefix and its source (ordoro_list_orders). The description adds only the endpoint path template, 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 — retrieving shipment/tracking details for one order — and enumerates the concrete payload (carrier, method, tracking number/URL, ship date, ETA, label cost, returns, dropship). It is clearly distinguishable from ordoro_get_order since it is scoped to shipping_info only.

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: call this when you need tracking/shipping data for a single order. However, it never states when to prefer this over ordoro_get_order (which likely also touches the order) or what to do when an order has no shipment, so the choice between siblings is left 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?

readOnlyHint=true already declares the safe-read profile, so the description earns credit for going further: it discloses the exact scope of the payload (price, cost, weight/dimensions, inventory totals, per-warehouse on hand/available/committed/location, suppliers, kit components, channel links) and the underlying endpoint. It does not mention auth or rate limits, which is acceptable for a read call.

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 tight sentence front-loads the lookup key before enumerating return fields, with the endpoint appended. The field list is dense but each item is informative rather than 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?

There is no output schema, so the description carries the burden of describing returns and does so broadly (inventory, stock per warehouse, suppliers, kits, channel links). An agent knows what it will get back, though it lacks detail on nesting or edge cases like an unknown 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?

Only one parameter (sku) and schema coverage is 100%, so the schema already documents it. The description restates 'by SKU' but adds no format hints or constraints beyond the schema's minLength/description.

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

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

States a specific verb (Get) and resource (one product by SKU) and enumerates the data domains returned. It is trivially distinguishable from the sibling ordoro_list_products, which returns many products.

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 single-product-by-SKU framing implies you should use this when you already know the SKU, but the description never names ordoro_list_products or states the when-not condition. 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?

With readOnlyHint=true already covering the safety profile, the description still adds value by disclosing the payload shape: supplier, warehouse, status, line items with quantities and unit price, plus shipping/payment methods and dates. No mention of error behavior for an invalid id, but for a read-only lookup the disclosure is solid.

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 retrieval action and returned fields come first, the raw endpoint reference last. Nothing is redundant or padded.

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

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

There is no output schema, so the description carries the burden of describing what comes back, and it does so with a field-level inventory. It stops short of full completeness by omitting identifier types and any notes on missing/empty lines.

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 parameter already documents both its meaning and its source ('from ordoro_list_purchase_orders'). The description only restates 'by its PO id', adding no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one purchase order by its PO id') and enumerates the returned fields, so the agent knows exactly what this retrieves. The word 'one' implicitly separates it from the sibling list tool, but no sibling is named explicitly, so it falls short of the 5 bar.

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

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

Usage is implied by 'by its PO id' — retrieve a single PO when you already have an id — but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. ordoro_list_purchase_orders) for the case where the agent lacks an id.

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 declare readOnlyHint=true, so safety is partly covered, and the description adds the underlying endpoint (GET /supplier/{supplier_id}/) plus the fields returned. With no output schema, describing the response contents is genuinely valuable. It stops short of error/not-found behavior or auth requirements.

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

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

Two short sentences, front-loaded with the purpose, followed by the returned fields and the raw endpoint. No filler or redundancy.

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

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

For a one-parameter read with no output schema, the description supplies the essential missing piece — what the returned record contains. Complete enough to invoke correctly; only edge-case behavior (missing/invalid id) is unaddressed.

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

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

Schema description coverage is 100% and the single parameter already documents its meaning and origin (from ordoro_list_suppliers). The description adds only 'by id', nothing beyond the schema, so the baseline 3 is correct.

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 ('Get one supplier by id') and enumerates the payload contents (address, contact details, dropship/PO settings), which cleanly separates it from ordoro_list_suppliers. It doesn't explicitly name the list sibling, but the singular 'one supplier by id' makes the boundary obvious.

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: use when you have a supplier id and need that record. There is no explicit when-to-use/when-not framing or mention of the alternative (ordoro_list_suppliers) in the description itself; that cross-reference lives only in the schema's parameter text.

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?

readOnlyHint=true already establishes the safety profile, yet the description adds real behavioral context by disclosing the pagination contract ('use offset for the next page') and the exact response envelope. It stops short of mentioning auth requirements or rate limits, which are not covered elsewhere.

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 what is listed, then pagination behavior, then the raw endpoint for reference. No filler and no 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 available, the description compensates by spelling out the return shape ({ count, limit, offset, comment: [...] }) and how to advance pages. For a simple read endpoint with three documented parameters, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding operational meaning to offset ('use offset for the next page') that goes beyond the schema's generic 'Number of results to skip' and ties limit/offset together as a paging mechanism.

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

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

States a specific verb and resource ('List the comments ... of one order') and further disambiguates the resource by defining what comments contain: internal notes plus the order's activity log. An agent can immediately separate this from ordoro_add_order_comment (write counterpart) and ordoro_list_order_tags (different resource).

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 'of one order' and the highlighted pagination, but there is no explicit when-to-use/when-not statement and no named alternative (e.g., 'to post a comment use ordoro_add_order_comment'). The agent must infer the context from the resource name alone.

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 supply only readOnlyHint=true, so the description carries most of the burden and it delivers: default sort, default page size behavior (via the schema) and the response envelope { count, limit, offset, order: [...] } with lines, addresses, shipping_info/tracking, tags and financials. It omits rate limits or any caveat about result caps beyond the schema's max.

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 sentences, front-loaded with purpose and scope, then filters, then return shape and the underlying API route. Dense and mostly waste-free; the long filter enumeration is slightly list-like but each item is informative.

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

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

For a 15-parameter, no-required, listing tool with no output schema and thin annotations, the description covers scope, defaults, filters and the response envelope well. Remaining gaps (rate limits, cap on total retrievable results, whether 'all' truly means unfiltered) 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 the schema already explains every parameter including enums and pagination; baseline is 3. The description adds only the sort default ('newest first by default') and restates a subset of filters (status, search, SKU, tag, warehouse, dates) while omitting sort, sales_channel and allocation_status.

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') plus scope ('across all sales channels, newest first by default') and enumerates the filter dimensions. It does not explicitly differentiate itself from neighbors like ordoro_list_return_orders or ordoro_get_order_counts, so sibling routing relies on the name rather than the text.

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 filter list implies when the tool is useful (querying orders by status, SKU, tag, warehouse, dates) and the 'newest first by default' note hints at default behavior, but there is no explicit when-to-use/when-not guidance or named alternative for narrow lookups such as ordoro_get_order.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the underlying HTTP verb and path (GET /v3/order/tag) and the shape of the returned records (id, name, color), which the schema does not express. It stops short of stating pagination behavior or ordering guarantees, but that is a modest gap given annotation coverage.

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, front-loaded clauses: what it lists, how the output is consumed, and the backing endpoint. Nothing is padded and the essential purpose leads.

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

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

There is no output schema, but the description compensates by enumerating the returned fields (id, name, color), and the pagination inputs are fully covered by the schema. For a simple, zero-required-parameter read tool this is close to complete; only the ordering and total-count behavior of the list remain 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% and both parameters (limit, offset) are fully documented there, so the baseline is 3. The description adds no parameter-level meaning beyond restating the resource; the field list (id, name, color) describes the response, not the inputs.

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

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

States a specific verb and resource ('List the account's order tags') plus the returned fields (id, name, color), which distinguishes it immediately from sibling list_* tools covering orders, products, suppliers, etc. It also names the sibling tools that consume its output, which no other list tool in the set does.

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

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

The description implies usage by telling the agent to feed the returned id into ordoro_add_order_tag / ordoro_remove_order_tag, so the workflow context is inferable. However, it never states when to call this versus alternatives, nor does it spell out pagination-driven repeats or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the response envelope ('Returns { count, limit, offset, products: [...] }') and the seven inventory total fields, which is genuine value given no output schema, but it says nothing about auth, rate limits, or default result size 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?

Front-loaded with purpose and inventory fields, then filters, then return shape; every sentence carries information. The trailing 'Ordoro API: GET /product/' is low-value plumbing but only costs a fragment.

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 supplies the return envelope and the inventory fields; with 0 required params and full schema coverage, the agent has what it needs to call it. Only the absence of sibling routing (list vs. get_product) keeps it short of 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 every one of the 16 parameters is already documented in the schema (enums, ranges, ISO-8601 format). The description's filter list merely restates a subset of those parameters at a higher level, adding no syntax or semantic detail beyond the schema.

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

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

States a specific verb and resource ('List products') plus the inventory totals it surfaces, which is far more informative than the title alone. It does not explicitly distinguish itself from the sibling ordoro_get_product, so 5 is not warranted, but the plural/list framing makes the split reasonably evident.

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

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

It enumerates the filter axes ('search, active, low inventory, oversold, needs_sync, warehouse, supplier, tag, kit status and updated date'), which implies when each filter is useful, but gives no when-not guidance and never names ordoro_get_product as the alternative for single-item 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It adds the backing endpoint (GET /purchase_order/) and the returned payload shape, but says nothing about pagination behavior, default result size, or ordering beyond what the schema already documents.

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

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

Two short sentences, front-loaded with the resource and returned fields before the filter list. Every clause is substantive; the trailing API path is mildly redundant but compact.

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 read-only list tool with full schema coverage and a readOnly annotation, the essentials are covered, and it even compensates for the absent output schema by naming the returned fields. Only pagination/default behavior is left implicit.

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 including sort, limit, offset and the date bounds is already fully documented. The description only restates the filterable categories at a high level and adds no syntax or format detail beyond the schema. 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 pairs a specific verb (List) with a specific resource (purchase orders to suppliers) and enumerates the returned fields (status, supplier, lines, expected delivery). The 'list' verb contrasts naturally with the singular sibling ordoro_get_purchase_order, though the description never names that alternative.

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

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

It states what can be filtered (status, SKU, tag, search, updated date), which implies the tool's retrieval role, but gives no explicit when-to-use guidance or exclusions relative to siblings like ordoro_get_purchase_order or ordoro_get_supplier.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds the underlying endpoint (GET /v3/return_order) and the shape of returned records, but says nothing about pagination behavior, result caps, or rate limiting that an agent listing records might care about.

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

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

Two short sentences, front-loaded with the resource and returned fields, with no padding. The endpoint mention is arguably redundant with readOnlyHint 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?

There is no output schema, so listing the returned record components (reference id, status, original order, lines, return label) usefully fills that gap, and all five parameters are covered by the schema. The main omission is usage context and pagination expectations.

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% – sort, limit, offset, search and status are all documented in the schema itself. The description references filtering by status only implicitly through its field list and adds no format or syntax detail, 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 (List) and resource (return orders/RMAs) and enumerates the fields returned (reference id, status, original order, lines, return label). This clearly separates it from the order-oriented siblings like ordoro_list_orders, though it never explicitly names a sibling to differentiate 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?

The description says what the tool returns but never states when to use it, when not to, or which alternative (e.g. ordoro_get_order) to prefer for related lookups. Usage is only inferable from the resource name, which matches the 'no guidance' tier.

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 readOnlyHint annotation already declares this as a safe read operation. The description adds useful behavioral context beyond annotations: the exact returnable fields, the fact that carrier credentials are never returned, and the underlying API endpoint. It still does not cover auth requirements, rate limits, or pagination 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?

The purpose is front-loaded and the carrier examples, returned-field list, and API endpoint are all relevant. It is slightly dense but contains 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 read-only listing tool with full schema coverage and no output schema, the description supplies the essential return fields and the credential-exclusion policy. No alternative routing is needed because there is no competing shipper-listing sibling.

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 fully documents the all, limit, and offset parameters. The description does not add parameter-specific meaning beyond the schema, which fits the baseline of 3 when structured fields carry the heavy lifting.

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

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

The description gives a specific verb ('List') and resource ('carrier accounts (shippers)'), then enumerates the connected carriers. It is immediately distinguishable from the order, product, and supplier listing 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 does not explicitly state when to use this tool versus alternatives or when not to use it. Usage is implied by the name and the absence of any similar sibling tool, but no routing guidance is provided.

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, so the safety profile is covered. The description adds the underlying endpoint (GET /supplier/) and the shape of returned records, which is useful context, but says nothing about pagination behavior, ordering, or result limits beyond what the schema states.

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

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

Two short sentences, with the resource and returned field set front-loaded ahead of the implementation detail. No filler or redundancy.

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 the pagination parameters are documented in the schema. It is nearly complete for a simple read tool; only ordering and default result-size behavior are 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%, so limit, offset, and search are already fully documented in the schema. The description adds no parameter-specific meaning (e.g., what fields 'search' matches), 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 ('List') and resource ('suppliers and dropshippers') and enumerates the returned fields (id, company name, address, contact email, dropship settings), so the agent knows exactly what it retrieves. It doesn't explicitly contrast with the sibling ordoro_get_supplier, though the plural/retrieval framing makes the distinction reasonably clear.

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

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

Usage is implied by the list-vs-get naming pattern against ordoro_get_supplier, but the description never states when to prefer this tool or that it returns a paginated collection rather than a single record. No exclusions or prerequisites 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, so the safety profile is covered. The description adds useful domain context ('ship-from locations') and return fields, but does not disclose pagination behavior, filtering scope, rate limits, or auth requirements beyond what the schema and annotations provide.

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

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

Two compact sentences with no filler: the purpose and return fields are front-loaded, and the API endpoint follows as supporting detail. Every element 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, listing the returned fields (id, name, address, default flag) is valuable and covers the core return shape. It stops short of explaining pagination behavior or search semantics, but those are already documented in the input schema.

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

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

Schema description coverage is 100%, so limit, offset, and search are already documented in the schema. The description adds no parameter-level meaning beyond that, which matches the baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List warehouses'), clarifies the domain meaning ('ship-from locations'), and names the returned fields (id, name, address, default flag). Sibling tools do not cover warehouses, so the 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?

Usage is implied by the name and resource, but there is no explicit guidance on when to call this versus other list tools, nor any prerequisites or exclusions. For a simple list endpoint with no overlapping siblings, this is minimally adequate.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the safety profile is covered. The description goes beyond them with 'The tag itself stays defined', which precisely scopes what is destroyed (the association, not the tag record) – genuinely useful context that annotations cannot express, though it stops short of stating auth requirements or the response 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?

Three short clauses, front-loaded with the 'WRITE:' mutability marker, then scope clarification, then the raw endpoint for traceability. No filler and nothing buried at the end.

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 two-parameter idempotent mutation with annotations covering the safety profile and a fully described schema, the description supplies what is missing (write marker, non-destructive-to-tag scope, endpoint). Only minor gaps remain, such as behavior when the tag is not present on 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 are documented in-schema with field formats and provenance ('including its sales-channel prefix (for example "1-1001")'). The description adds only the redundant 'by id' qualifier, so this sits at the baseline 3 where the schema carries the load.

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

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

States a specific verb+resource combination ('remove a tag ... from an order') and immediately disambiguates from the sibling ordoro_add_order_tag by naming the inverse operation. The parenthetical '(by id)' plus the concrete DELETE endpoint pin down exactly what is being removed and how.

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: an agent can infer this is the counterpart to ordoro_add_order_tag, and the schema provenance hints ('from ordoro_list_order_tags') steer the agent to fetch a valid tag_id first. However, there is no explicit when-to-use/when-not guidance, e.g. what to call instead if the intent is to delete the tag definition itself rather than the association.

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