Brightpearl MCP by usefulapi

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

Leads with 'WRITE:' and explains the visibility model (private staff-only by default, public to the customer portal when is_public is true), that the note id is returned, and that notes cannot be removed with this server. That last point plus the returned id gives the agent the non-idempotent, hard-to-reverse consequences that the destructiveHint annotation only hints at.

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 operation type and purpose, then layers visibility, return value, and irreversibility, ending with the endpoint. Every sentence carries distinct information with no 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?

Covers what the tool does, its rules, and its return value even though no output schema exists, so nothing an agent needs to invoke it correctly is missing. The added note about deletion limits compensates for the sparse annotation set.

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 in the schema. The description reinforces the is_public default and privacy meaning but adds no new syntax, format, or constraint detail beyond the schema fields.

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?

Uses a specific verb and resource ('add a note to a contact's timeline'), which cleanly separates it from brightpearl_add_order_note by resource type. It never names the sibling, so the differentiation is implicit rather than stated.

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?

Supplies a concrete use case ('record of correspondence') and clarifies visibility semantics that determine how the note is used. It gives no exclusions or explicit alternative calls, but for a simple write endpoint the context is 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 the write, non-idempotent, destructive, open-world profile, but the description adds real value beyond them: the note is staff-private by default, is_public exposes it on the customer portal, and the return value is the new note id. The 'notes cannot be removed with this server' line usefully tells the agent there is no cleanup path. Slight tension with destructiveHint=true is worth noting, but it reads as metadata caution rather than a contradiction.

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 with the 'WRITE:' mode marker front-loaded, followed by visibility behavior, return value, irreversibility, and the endpoint. Nothing is padded or repeated.

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 three-parameter write tool with no output schema, the description covers the mutation type, visibility semantics, the return shape ('new note id'), and the lack of a delete path. An agent has everything needed to call it correctly and interpret 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 description coverage is 100%, so all three parameters (text, order_id, is_public) are fully documented in the schema. The description's statement about is_public largely restates the schema's 'Visible to the customer on the customer portal' text, adding no format, length, or ordering details beyond structured data.

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 ('WRITE: add a note to an existing order') plus the underlying endpoint. The 'order' qualifier separates it from brightpearl_add_contact_note and the 'add' verb separates it from brightpearl_get_order_notes 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?

Usage is implied rather than stated: it clarifies the privacy default and notes that removals are impossible here, which nudges the agent away from expecting a delete path. However, no explicit when-to-use/when-not-to-use guidance or named alternatives are given (e.g. reading notes via brightpearl_get_order_notes, or contacting notes via brightpearl_add_contact_note).

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 useful content-level context — the response is key/value pairs and names several of the keys — but says nothing about permissions, whether values change, or the shape/format of the payload. With annotations carrying the safety burden, this is adequate but not rich.

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 dense sentence front-loads the resource and then enumerates the useful keys; the trailing endpoint path adds traceability at low cost. No filler, though the key list is a run-on rather than structured and the endpoint reference is of marginal value to 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?

There is no output schema, so the description must convey what comes back — it does so by naming the returned keys and the key/value-pairs shape. For a zero-parameter read tool with full annotation coverage, that is close to sufficient, with only the exact value formats or nesting left unspecified.

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 there is nothing the description needs to disambiguate; baseline 4 applies. The description correctly implies no inputs are required by framing the tool as a pure account-level fetch.

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 (implicitly 'get'/'retrieve') and a precisely scoped resource — the Brightpearl account's configuration — and enumerates its contents (base currency, tax scheme, time zone, status ids, nominal codes, weight unit, warehouse flag). This is clearly separable from the sibling list_*/search_* tools, though it never explicitly contrasts itself with them.

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: fetch this when you need account-level defaults such as currency, tax scheme, or default status ids before performing other operations. However, it does not say when to prefer it over overlapping siblings like brightpearl_list_warehouses or brightpearl_list_tax_codes, nor does it mention prerequisites or caching considerations.

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 50-id batch ceiling, the optional payload expansions, and the underlying GET endpoint. It stays silent on what happens with ids that don't exist (partial results vs. error), which is the main remaining behavioral unknown for a batch fetch.

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?

Purpose is front-loaded in the opening clause, and the long semicolon-separated field list is dense but each clause carries real information about return content. Slightly over-packed for a single sentence, but 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?

With no output schema, the description carries the burden of describing returns and does so thoroughly via the field inventory and the two opt-in expansions. The gap is failure semantics for missing/invalid ids, which matters for a batch-by-id 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% – all three parameters, their bounds (1-50 ids, maxItems 50) and both booleans are already documented in the schema. The description reinforces the id limit and names the payload each flag unlocks (custom field values, full postal addresses), but adds no syntax or format detail beyond that, 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: 'Full records of one or more contacts by id', followed by an explicit inventory of returned fields and a batch cap of 50. The 'by id' scoping implicitly separates it from brightpearl_search_contacts, but that sibling is never named, so the differentiation is inferred rather than stated.

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 'by id' framing and 'Up to 50 ids' hint that this is a batch retrieval for already-known ids, implying search_contacts is the right tool when ids are unknown. However, no explicit when-to-use/when-not guidance or alternative is 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds value beyond them by listing what each note contains (text, author contact id, date, customer-portal visibility, order status at the time) and citing the underlying endpoint path. It omits pagination/result-limit behavior, which is the main remaining gap.

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

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

Two tight clauses: the returned content first, then the endpoint. No filler sentences, and the core purpose is front-loaded ahead of the field enumeration.

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 is what makes this definition sufficient to call correctly. What is missing is edge-case behavior (empty note list, pagination, ordering of notes), which keeps it short of 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 coverage is 100% and there is only one parameter (order_id), which the schema already documents. The description adds no extra meaning such as id format or where to obtain the id; baseline 3 applies.

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

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

States a specific verb+resource+scope: all notes on one order, with the returned fields enumerated. It implicitly distinguishes itself from the write-side siblings brightpearl_add_order_note and brightpearl_add_contact_note, but never names an alternative 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?

The read-only framing implies this is the retrieval counterpart to brightpearl_add_order_note, but there is no explicit 'use this when...' guidance, no note about when to prefer search_orders or the goods-in/out note searches 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: the batch cap of 50 ids, the breadth of the payload including order rows, and the underlying endpoint path. It stops short of describing behavior on missing/invalid ids, which is the one meaningful gap.

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

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

A single dense sentence front-loads the core action and the field inventory, followed by the endpoint reference. It is information-packed rather than bloated, though the long field enumeration is somewhat list-like rather than scannable.

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 usefully tells the agent what comes back, which is the main thing the description must compensate for. Error handling for nonexistent ids is the remaining omission, but for a read-only batch getter this is close to complete.

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

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

Schema coverage is 100%, with both order_ids (1-50) and include_custom_fields documented inline, so the schema carries the parameter burden. The description's 'Up to 50 ids' merely restates maxItems and adds nothing about include_custom_fields or id validity, 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 ('Full details of one or more orders by id') and enumerates the returned fields, so the agent knows exactly what it retrieves. The 'by id' scoping implicitly separates it from brightpearl_search_orders, but the sibling is never named, so differentiation requires 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?

Usage is only implied: fetching known ids is the natural reading of 'by id', and the 50-id cap hints at batch lookups. There is no explicit statement of when to prefer this over brightpearl_search_orders or what to do when ids are unknown, so the agent must infer the 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the response structure (totals across warehouses plus per-warehouse figures, optional location breakdown, on-order quantities) and the 50-id batch limit, which materially affects how an agent plans calls. Missing only things like auth or rate-limit notes.

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?

Very dense and front-loaded: the core output fields come first, optional modes second, the batch limit next. The trailing endpoint path is marginally useful and nothing is wasted, though the single run-on structure is slightly harder to parse than a bulleted form.

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 correctly shoulders the burden of describing return shape, and it does so well. It is nearly complete for a read-only availability lookup; only behavior for non-stock-tracked products or empty/invalid id results 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 all three parameters are already documented, making 3 the baseline. The description mirrors the optional flags ('optionally per location, with on-order quantities') without adding syntax, defaults, or edge-case meaning 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 (retrieve stock availability for stock-tracked products) and enumerates the exact figures returned (inStock, onHand, allocated, inTransit). This clearly separates it from siblings like get_products or get_product_prices, which serve different data needs.

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 (query stock levels for up to 50 product ids) but never says when to choose this over get_products or search_products, nor names any alternative. The constraint that it only works for stock-tracked products is a useful implicit boundary, but routing guidance 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?

Annotations already establish read-only, non-destructive behavior, and the description adds useful output transparency: currency, SKU, and quantity-break price structure. It does not mention pagination, auth requirements, or error behavior, but for a read-only GET query the added detail is substantial.

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 what is returned and stays compact, with no filler sentences. It is slightly dense and run-on, but every clause carries useful information about output shape, limits, optional filtering, or endpoint.

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 explains the return shape and the quantity-break map. It also covers the optional price-list filter and limit, but does not address pagination or default behavior when price_list_ids is omitted beyond implication.

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 schema already documents both parameters. The description adds meaning by identifying brightpearl_list_price_lists as the source for price_list_ids and clarifying that omitting price_list_ids retrieves prices across price lists, though it repeats the 50-product limit already 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?

The description states a specific retrieval operation: product prices per product and price list, including returned fields such as currency, SKU, and quantity-break price map. It also distinguishes the tool from brightpearl_list_price_lists by explaining that price list IDs come from that sibling tool.

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 clearly explains that product_ids are required and limited to 50, while price_list_ids are optional and sourced from brightpearl_list_price_lists. It gives usage constraints but does not explicitly compare against siblings like get_products or get_product_availability, so it falls short of full when/when-not guidance.

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

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 genuinely useful context beyond that: the retrieval is id-keyed and capped at 50 ids per call, plus the breadth of what is returned. It says nothing about behavior with unknown or invalid 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?

Front-loaded with purpose, then a dense field enumeration, then the batching limit. Slightly noisy because the raw endpoint string duplicates what the server already knows, but the rest 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, the field enumeration does the job of telling an agent what comes back, and the 50-id cap sets expectations for batching. Missing only edge-case behavior for unknown ids and any hint about the optional custom-fields flag.

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 both product_ids and include_custom_fields are already documented. The description's 'Up to 50 ids' restates the schema's maxItems and adds no syntax or format detail, and include_custom_fields is not mentioned at all.

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 ('Full details of one or more products by id') and enumerates the returned facets, which makes clear it is a detail-fetch keyed on ids. The 'by id' phrasing implicitly distinguishes it from brightpearl_search_products, but no sibling is named 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?

Usage is only implied: an agent must infer it should call this when it already has product ids and use brightpearl_search_products otherwise. No alternative or prerequisite is stated explicitly.

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, so safety is covered. The description adds value beyond that by enumerating the exact fields returned (including the SO/PO/SC/PC order type codes and the draft state), which matters because there is no output schema; the endpoint path also confirms it is a plain GET listing. It does not mention whether the list is paginated or whether it includes system/hidden statuses.

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 the tool returns and followed by the concrete use of the ids. The parenthetical field enumeration is dense but every item earns its place given the absence of an output schema.

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

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

For a zero-parameter read tool with annotations covering the safety profile, the description does the heavy lifting by describing the returned record shape. What is missing is minor: no note on whether the full set is returned or whether disabled/hidden statuses are included, and no explicit pointer to the update tool for the change-status workflow.

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 of 4 applies; there is no parameter semantics gap because there is nothing to document. The description correctly implies a no-argument, account-scoped listing.

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 specific resource (the account's order statuses) and enumerates the fields returned (id, name, order type code, sort order, disabled, customer visibility, state), plus the underlying GET endpoint. It is clearly a read/list operation distinct from mutation siblings, though it never explicitly contrasts itself with the similarly-named brightpearl_list_order_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?

"Use the ids to filter orders or to change an order's status" gives a concrete downstream purpose, which is good implied guidance. However, it never names the alternatives an agent would need — brightpearl_update_order_status for the actual change and brightpearl_search_orders for the filtering — nor states any when-not-to-use condition.

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, so safety is covered. The description adds genuinely new behavioral context: this is a closed, static enumeration of exactly four values, so the agent knows the result set is tiny and unchanging and needs no filtering or pagination thought.

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

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

One dense sentence plus the endpoint path; the enumerated mappings are front-loaded and there is no filler. Every clause conveys either the return contents or the retrieval target.

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 and no parameters, the description steps in to document the return values inline, which is the right call. The only small gap is that it never states the response shape (array of objects vs. map), so the agent must inspect the result to know how to iterate.

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 the schema carries nothing to explain and the baseline is 4. The description usefully goes beyond parameter talk by spelling out the id-to-code mapping the tool returns, which is the only 'semantics' that matter here.

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 ('the four order types'), then enumerates exactly what comes back: ids 1-4 with codes SO/PO/SC/PC and their meanings. An agent can tell this apart from sibling lookups like list_order_statuses or list_payment_methods without opening anything else.

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 'for the order search' pins the downstream use case, implicitly telling the agent to call this before search_orders when it needs an orderTypeId filter. It does not explicitly exclude alternatives or say when this is unnecessary (it is a fixed taxonomy, so arguably always safe to call), but the context is clear.

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 genuinely new context by enumerating the returned attributes, including nested bank account details with currency and nominal code — information not available anywhere else since 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?

A single compact sentence listing return fields plus the endpoint path — zero waste and front-loaded. The phrasing 'The payment methods (...)' is slightly elliptical but not padded.

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

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

With no parameters and no output schema, the main risk is an agent not knowing what comes back; the description closes that gap by naming the return fields and the nested bank account structure. Only the usage context (why an agent would call it) 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No misleading parameter claims are made.

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 (payment methods) and the GET endpoint makes the list/read nature explicit, and it enumerates the fields that come back. It is clearly distinct from siblings like list_shipping_methods or list_tax_codes by resource, though it never explicitly contrasts them.

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 tool versus alternatives, nor any stated prerequisite or typical use case (e.g., resolving a payment method ID seen on an order or customer payment). 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 the safety profile is covered. The description adds useful detail about returned fields and the special cost price list, but says nothing about pagination, ordering, or completeness of the list.

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 short and front-loads the key information about returned fields and the special id 0 case. It is telegraphic but contains no filler; a slightly more structured phrasing might improve readability.

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

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

For a zero-parameter listing tool with no output schema, the description suitably explains the return fields and the special cost price list id. It could mention whether the result is paginated or exhaustive, but the essential context is present.

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 there are no parameter semantics for the description to explain. The baseline for zero-parameter tools is 4; the description does not need to clarify 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?

The description clearly identifies the resource (price lists) and the fields returned, including the special meaning of id 0 as the cost price list. It does not explicitly distinguish this from sibling tools like get_product_prices, but the purpose is otherwise 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?

There is no guidance on when to use this tool versus alternatives such as brightpearl_get_product_prices or the search/list siblings. The usage is only implied by the tool name and resource description.

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 underlying endpoint but says nothing about pagination, result size, or whether all methods are returned in one call — gaps that matter for an open-world list endpoint.

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 compact sentence with no waste, and the field list is front-loaded. The trailing raw endpoint path is slightly cryptic but harmless and adds traceability.

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 zero-parameter, read-only list tool with no output schema, the description supplies exactly what is missing: the shape of the returned records. With annotations covering safety, nothing an agent needs to call this correctly is absent.

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. The description's field list is about outputs, not inputs, and there are no inputs to explain.

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 identifies the specific resource (shipping methods) and enumerates the fields returned, so an agent knows exactly what data it gets back. It doesn't explicitly say 'list/retrieve' or contrast with siblings like list_payment_methods or list_warehouses, but the resource is unambiguous, so 4 rather than 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?

There is no statement of when to use this tool, no prerequisites, and no named alternative. The only implied guidance is that the tool returns all shipping methods with no filtering, which the agent must infer from the empty schema.

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 underlying endpoint (GET /accounting-service/tax-code) and enumerates the returned fields, which is useful, but says nothing about ordering, pagination, or result size. With annotations carrying the behavioral burden, a 3 is appropriate.

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 short sentence plus an endpoint, with nothing redundant. It is front-loaded and easy to scan, though the fragment style borders on under-specification rather than true conciseness.

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 zero-parameter read tool with full annotation coverage, the description is adequate: it names the resource, lists the core fields, and gives the endpoint. However, with no output schema, it does not say whether this returns all tax codes or what the response envelope looks like, leaving a modest gap for an agent assembling a request flow.

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 there is nothing to disambiguate; the baseline for a 0-param tool is 4. The description's field list is about output, not input, so no parameter semantics are needed or missing.

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 is a noun fragment ('The tax codes (id, code, description, rate)') with no verb; the verb 'List' only appears in the name and title. It does identify the resource and its returned fields, but an agent must infer the operation from the name rather than the description. It is distinguishable from siblings mainly because no other sibling mentions tax codes.

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 use this tool versus alternatives, no mention of prerequisites, and no note about whether results are filtered, paginated, or complete. The only routing signal is the word 'tax codes' itself.

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 returned field set and the HTTP endpoint, which is useful since no output schema exists, but says nothing about volume, pagination, or whether inactive/closed warehouses are included.

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 fragments with no filler: what a warehouse record is, what the ids are for, and the endpoint. The purpose statement is front-loaded 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?

For a zero-param read tool with no output schema, listing the response fields is the right move and partly fills the gap. Still missing are scope details an agent would want — whether all warehouses are returned at once, whether inactive ones appear, and whether there is any pagination or filtering.

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 and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies; the field enumeration describes the response rather than 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?

The description names the resource (warehouses) and enumerates what each record contains (id, name, type, address id, click-and-collect settings, weekly operating hours), plus the backing endpoint GET /warehouse-service/warehouse. The listing verb is implicit rather than stated, and there is no sibling differentiation, but no sibling in the tool set covers warehouses 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?

'Use the ids for stock and order filters' gives one concrete downstream use case, which is real guidance. However it never states when to call this versus alternatives, or any prerequisite/exclusion — the when-to-use is only implied by the id-filtering note.

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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful context beyond annotations: the exact row shape (brandId, brandName, createdOn, updatedOn) and the underlying endpoint, which help an agent interpret 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 compact clauses: the action with its key filter and returned fields, then the endpoint. Nothing is wasted and the core purpose is front-loaded.

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 required parameters and no output schema, the description appropriately covers what a caller needs: the searchable field and the returned row fields. Pagination details are already in the schema, so nothing critical 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%, so all three parameters are fully documented in the schema, including pagination guidance. The description's 'by name' adds no meaning beyond the schema's 'Brand name (case-insensitive match).' 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 ('Search product brands by name') and names the returned fields, so it is clearly distinct from search_products or search_categories. It does not explicitly contrast with siblings, but the resource scope 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?

Usage is implied: use this to find brands by name. There is no explicit when-to-use/when-not-to-use guidance or mention of alternatives, and it doesn't clarify that name is optional (all brands can be listed).

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 useful context by listing the fields returned in each row and the underlying endpoint, but says nothing about pagination limits or result caps beyond what the schema implies.

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 compact sentence that front-loads the action and resource, then summarizes return fields. Nothing is wasted, though the endpoint path is of marginal use to 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?

For a read-only paginated search with no output schema, the description supplies the key return-field list and the schema fully documents filtering and paging. It is nearly complete, missing only explicit guidance on result limits or how paging terminates.

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 (name, active, page_size, parent_id, first_result) is already well documented, including the next_first_result paging hint. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Search Brightpearl product categories') and enumerates the returned row fields, making the resource distinct from siblings like search_products and search_brands. It stops short of naming an explicit alternative, so it lands at 4 rather than 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?

There is no statement of when to use this tool versus the sibling search/filter tools, nor any prerequisites or exclusions. Usage is only implied by the verb 'Search' and 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 cover readOnly/openWorld/destructive, so the description adds value by disclosing that all filters are optional and combine with AND, and by enumerating the result row fields — important since there is no output schema. It does not mention pagination caps or result limits beyond what the schema says.

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 substantive sentences front-load purpose and the alternative, with the endpoint as a trailing technical note. The field enumeration is slightly listy but earns its place given the absence of an output schema.

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

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

For a 21-parameter, zero-required search with no output schema and no annotations gap, the description supplies the two things the schema cannot: AND-combination semantics and the shape of returned rows. Nothing critical is missing, though error behavior and search-match semantics are left to the 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 coverage is 100%, so the baseline is 3, but the description contributes a genuinely non-schema fact: filters are all optional and are AND-combined, which governs how to compose 21 parameters. It adds no per-parameter detail beyond that.

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 ('Search contacts') and immediately scopes what a contact is ('customers, suppliers and staff'). It also names the sibling brightpearl_get_contacts as the full-record alternative, so an agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent to brightpearl_get_contacts 'for the full record', which is the key alternative among the 24 siblings. It does not state when-not-to-use conditions (e.g. prefer exact_primary_email lookups versus name search), so it falls short of 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful value by enumerating the returned fields (no output schema exists) and by giving the underlying endpoint, but it says nothing about paging behavior, result caps, or whether an unfiltered call returns everything.

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 clauses: what it searches plus the row shape, then the endpoint. Front-loaded and waste-free, though the field enumeration is dense and could be a structured return description instead.

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 12-parameter, zero-required, read-only search tool with no output schema, the description does cover output shape, which is the main gap the schema leaves. Filtering strategy (all params optional, results could be huge) and pagination contract are left to the schema, which mostly handles them.

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 12 parameters is already documented with format and default details (date handling, page_size 1-500, first_result/next_first_result paging). The description adds no parameter-specific semantics, so the baseline 3 applies.

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

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

States a specific verb+resource plus scope: "Search payments received against sales orders", and enumerates the returned row fields, which lets an agent distinguish it from sibling search tools like brightpearl_search_orders. It does not explicitly name an alternative, but 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?

The description gives no when-to-use context, no prerequisites, and no alternatives (e.g., search_orders vs. this tool, or how to page through results). The only navigation hint towards a sibling, brightpearl_list_payment_methods, appears in the schema, not the description.

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 safety (readOnly, non-destructive, openWorld), so the description's real contribution is the per-row field inventory (purchaseOrderId, batchId, receivedQuantity, onHand, etc.), which substitutes for the missing output schema and tells the agent exactly what it gets back. It omits any note on result volume or that paging uses next_first_result, though the schema covers that.

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 in the opening clause and the endpoint anchor closes it; nothing reads as filler. The field enumeration is dense but earns its place because no output schema exists.

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 9-parameter, all-optional search tool with no output schema, the description supplies the missing return shape and endpoint, which is the main gap an agent would otherwise face. What remains absent, when to prefer this over related availability/order tools, is a usage rather than a completeness 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 description coverage is 100% and every filter already documents itself (batch, product, warehouse, purchase order, received date range, paging, sort). The description only alludes to filtering 'by batch and location', adding no new semantics, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (goods-in records / stock received against purchase orders, by batch and location), which is concrete enough to distinguish it from the goods-out counterpart by name alone. It does not explicitly name any sibling as an alternative or exclusion, so it stops short of 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 sentence says when to reach for this tool versus brightpearl_search_goods_out_notes, brightpearl_get_product_availability, or brightpearl_search_orders. The field list implies what questions it can answer, but no usage condition or exclusion is 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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the description's added value is the row shape, which it discloses in full. It does not describe pagination or default sorting, though the schema's first_result and newest_first descriptions largely cover those.

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

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

A single front-loaded sentence that defines the resource before enumerating fields. The field list is long but earns its place because there is no output schema; the raw endpoint path is the only unearned 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?

For a 13-parameter, zero-required search tool with no output schema, the description compensates by enumerating returned row fields and their meaning. Nothing critical to correct invocation is missing, though pagination flow is left to the 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 the schema already documents all 13 filters including date formats and paging semantics. The description adds no filter-level meaning beyond that 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?

States a specific verb and resource ('Search goods-out notes') and immediately defines it in domain terms ('pick/pack/ship records of sales orders'), which distinguishes it from the goods-in sibling. The trailing endpoint is redundant but harmless.

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 resource definition and filter semantics, but there is no explicit when-to-use or when-not-to-use guidance, and no routing toward brightpearl_search_goods_in_notes or brightpearl_search_orders as alternatives.

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 behavior: filter combination semantics and the shape of each result row (a summary, not the full order). It does not state result caps or pagination limits beyond what the schema implies, which keeps it just 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?

Front-loaded and dense; the routing hints come immediately after the scope statement. The trailing 'GET /order-service/order-search' is transport noise and 'and more' in the field list is slightly imprecise, costing a point but not readability.

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

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

For a 20-parameter, zero-required search with no output schema, the description supplies the missing pieces: what a result row contains, how filters combine, how to resolve enum-like ids, and where to go for full detail. An agent can construct and follow up on a query from this alone.

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% across 20 params, so the baseline is 3. The description still contributes: the AND-combination rule for filters is a genuine semantic addition not expressed in the schema, and it clarifies that results are summary rows keyed by orderId rather than full orders.

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

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

Opens with a specific verb and the exact resource families covered (sales orders, sales credits, purchase orders, purchase credits), so the agent knows precisely what this returns. It also names brightpearl_get_orders as the tool for full order detail, cleanly separating it from the sibling.

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?

States that all filters are optional and combine with AND, which tells the agent how to build a query. It explicitly routes the agent onward for the two most likely follow-ups: brightpearl_get_orders for the full order and brightpearl_list_order_types / brightpearl_list_order_statuses to resolve ids.

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 real value by enumerating the exact fields returned in each result row — critical since there is no output schema — plus the AND semantics of filters and the underlying endpoint. It omits default ordering/page-size behavior, but that is documented per-parameter 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?

Front-loaded with purpose, then the filter-combination rule, then the return-field list that substitutes for a missing output schema. The 16-field enumeration is long but earns its place; only the trailing raw endpoint adds marginal 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 0 required params among 22, full schema coverage, and no output schema, the description supplies the two things an agent would otherwise lack: what comes back and how filters interact. Pagination and defaults are delegated to the schema, which is acceptable here.

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, and the description adds cross-parameter semantics the schema cannot express: all filters are optional and combine conjunctively. That combinatorial rule meaningfully affects how an agent composes a call.

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 ('Search the product catalogue') and differentiates from the sibling brightpearl_get_products by scope (search vs. full details). An agent immediately knows this is the lookup tool and which tool returns richer records.

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 says every filter is optional and combines with AND, and names the alternative ('Use brightpearl_get_products for full details'). It does not spell out when-not to use it (e.g., searching by exact id vs. product_ids), but the context for selection is clear.

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 mark this as a destructive, non-idempotent write, and the description adds important behavior beyond them: Brightpearl adds an order note, status changes can trigger alerts and automations, and cancellation removes reservations and coupons and is refused under certain conditions. These side effects and preconditions are exactly what an agent needs before invoking a destructive write.

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 compact and front-loaded: it opens with 'WRITE' and the core action, then layers constraints, side effects, and refusal conditions. Every sentence carries operational value, including the endpoint reference.

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 the lack of an output schema, the description is complete enough for correct invocation: it covers the write nature, status id source, validity requirements, side effects, destructive cancellation behavior, and refusal conditions. Annotations reinforce the safety profile, and no critical missing context is apparent.

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 useful semantic constraints for order_status_id by explaining where valid ids come from and what conditions the status must satisfy. It adds less detail about the note and note_is_public parameters beyond what the schema already documents, keeping it from a 5.

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 verb and resource: 'move an existing order to another status.' It also distinguishes this write operation from the sibling read/list tool by pointing to brightpearl_list_order_statuses for status ids, so an agent can identify the tool without opening its 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 gives clear usage context: status ids must come from brightpearl_list_order_statuses, the target status must exist, be visible, and match the order's type, and cancellation is refused when goods-out notes or payments exist. It does not explicitly name alternatives for edge cases, but the operational guidance is concrete.

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