DecoNetwork MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, and the description adds real value on top: the append-only semantics ('each call adds a new note'), audience visibility (staff only, not sent to the customer), and the underlying endpoint. It does not cover permissions or rate limits, which keeps it from 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?

Three compact sentences, front-loaded with the 'WRITE' signal and the internal-visibility constraint, then the append warning, then the endpoint. Nothing is wasted and nothing essential 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 mutation tool with no output schema and fully documented parameters, the description supplies the mutation type, the repeat-call warning, and the visibility semantics an agent needs before invoking. Only error behavior and any confirmation/return detail are absent, which is minor.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including order_line_id's 'attach to this line item instead of the order' behavior. The description restates the order_line_id routing but adds no syntax or format guidance 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 ('add an INTERNAL note ... to an order, or to one line item'), and the 'visible to staff, not sent to the customer' clause removes any ambiguity about note type. It does not explicitly contrast itself with the sibling tools, though none of them create notes, so confusion risk is low.

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

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

Usage is implied rather than stated: it is clearly the tool for internal, staff-visible notes as opposed to customer-facing communication. The only explicit guidance is 'Each call adds a new note, so do not repeat it', which is a non-idempotency warning rather than a when-to-use vs alternative rule.

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?

Goes well beyond the readOnly/openWorld annotations: it discloses the data-hygiene behavior (card numbers, coupons, credential-bearing document/media links stripped), that status codes are spelled out, that workflow and PO data are opt-in, and that supplier catalog tools are unavailable. Missing is behavior on an unknown invoice number (empty result vs error) and any auth/rate-limit note, which would complete the picture.

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

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

Front-loads the core promise ('One order by invoice number with everything the API holds') and then enumerates payload contents in a compact run-on list. The trailing '(invoice number condition)' and the catalog-tools caveat are slightly out of place but each carries information; nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly by enumerating the order payload sections and noting redactions and status-code formatting. Combined with the endpoint reference and the optional-depth flags, an agent has enough to call it correctly and anticipate what comes back.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including that include_po_data implies workflow data. The description only restates that workflow items and PO data are 'optional', adding no syntax, format, or default nuance 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?

States a specific verb and resource ('One order by invoice number') and immediately scopes it: 'everything the API holds', enumerating line items, payments, refunds, shipments, notes, taxes, store. This clearly separates it from siblings like deconetwork_search_orders and deconetwork_list_orders_due, which return sets rather than one fully-hydrated 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?

Implicitly positions itself as the single-order detail fetch versus the search/list siblings by emphasizing 'all line items ... everything the API holds', and flags the optional workflow/PO depth via the include flags. It also states a useful constraint ('Supplier catalog tools are unavailable') and pins the underlying call (GET /api/json/manage_orders/find), but never explicitly says when NOT to use it (e.g., when you only have a customer name, use search_orders).

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 genuinely non-obvious behavior: default exclusion of cancelled, deleted and shipped orders, UTC default window, and soonest-first ordering. It doesn't mention pagination limits or rate limits, but the pagination params are documented 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?

Three dense sentences: scope and defaults first, then filtering behavior, then the use case and endpoint. No filler and nothing buried.

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

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

With no output schema, the description still signals the return shape ('compact summaries', sorted) which is what an agent needs. The only gap is that 'compact summaries' is not unpacked, but every parameter is documented and no required inputs exist.

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

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

Schema coverage is 100%, so baseline is 3, and the description still adds value by explaining the default window semantics and the meaning of include_closed as 'see the closed ones'. It doesn't clarify date string formats for due_from/due_to, which the schema also leaves as plain 'string'.

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 ('Orders due in a date window'), plus scope defaults, sort order and output shape ('soonest first, as compact summaries'). This is clearly distinguishable from get_order (single record) and search_orders (arbitrary criteria).

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

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

Gives an explicit triggering question ('what has to ship this week?') and explains the default exclusion behavior with a named escape hatch (set include_closed). It stops short of naming a sibling alternative for arbitrary order queries, but the usage context 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?

Adds material behavior beyond the read-only/open-world annotations: the default 30-day window, ANDed conditions, the crucial fact that order_status is applied to the fetched page because the vendor has no documented status filter, the 100-row cap, and offset-based paging. It also lists the return payload fields.

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

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

Three dense, front-loaded sentences that place the scope and default behavior first and the sibling pointer second. Slightly compressed by listing all five date axes, but nothing is pure 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 covers the return shape (invoice number/order_id, statuses in words, dates, amounts, contacts, shipping, tracking, line items), pagination, default behavior, and the filter quirk. Nothing an agent needs to invoke it correctly appears 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 already 100%, so baseline is 3; the description adds cross-parameter meaning the schema cannot: filter conjunction, the default date window, and especially that order_status is a post-fetch narrowing requiring another filter to be useful. It does not mention the sort_by default shown in 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 plus the exact filter axes (five date ranges and/or invoice number), and explicitly says to use deconetwork_get_order for a single order. It does not differentiate from deconetwork_list_orders_due, which overlaps on due-date queries, so an agent choosing between them is left to infer.

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 strong when/how guidance: conditions are ANDed, no filter returns the last 30 days by date ordered, order_status must be combined with a date range or invoice number, and results page via next_offset. The one missing routing rule is when to prefer deconetwork_list_orders_due instead.

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

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

Beyond annotations marking it destructive and non-idempotent, the description discloses irreversibility through the API, customer-email side effects with the exact default and whole-order restriction, tracking-number storage only for shipped status, and scoping rules for partial updates. This is rich behavioral context that materially reduces misuse risk.

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 definition is dense but front-loaded: it starts with the write action and scope, then covers irreversibility, side effects, partial-update mechanics, and the endpoint. Every sentence adds operational value with 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?

Given eight parameters, no output schema, and rich annotations, the description provides enough context to call the tool safely: scope, status constraints, email side effects, irreversibility, and endpoint. No critical behavioral or parameter guidance 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, but the description adds meaningful semantics beyond the schema: contact_customer sends an email only on whole-order changes and defaults to false, shipping_code applies only to shipped status, and workflow_item_id plus qty target part of a line. These details help an agent choose and combine parameters correctly.

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 write action and resource: moving an order, line item, or part of a line item to 'produced' or 'shipped'. It clearly distinguishes the three scopes and names the exact endpoint, so an agent can identify the operation 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?

It gives explicit conditions for contact_customer, order_line_id, workflow_item_id, and qty, and warns that the action cannot be undone through the API. It does not explicitly route the agent to a sibling alternative, but no direct alternative exists for this mutation; the guidance is clear and actionable.

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