Inventory Planner MCP by usefulapi

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real behavioral context on top: what a draft does and does not do ('moves no stock or money'), and that line items are variant id plus replenishment quantity. This is exactly the kind of consequence information structured fields cannot express.

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

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

Four tightly packed sentences, front-loaded with the write intent and endpoint, then the draft semantics, then scope exclusions, then the line-item shape. No filler and every sentence carries information an agent needs.

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 7-parameter, 3-required write tool with no output schema, the description covers the operation's meaning and side-effect profile well, and annotations cover safety. Minor gaps remain: it does not say whether vendor/warehouse must already exist in Inventory Planner or how currency defaults are handled.

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 57%, and the description only clarifies the 'items' array shape ('a variant id plus the quantity to order'), which the schema already documents. The remaining parameters (vendor, warehouse, currency, reference, notes, expected_date) get no added meaning in the description beyond what their schema descriptions state. Adequate but not compensating for the coverage gap.

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 an explicit verb+resource ('create a purchase order with status "draft"') and even names the underlying endpoint (POST /api/v1/purchase-orders). The scope qualifier 'Purchase orders only (no transfers or assembly orders)' separates it from the other PO-related siblings, and 'create' vs 'update_draft_purchase_order' 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?

Clearly frames the use case: a draft is a planning artifact that is NOT sent to the vendor and NOT saved to connected systems, so an agent knows this is the right call when staging a plan rather than executing a purchase. It also states exclusions (no transfers or assembly orders). It stops short of naming the sibling (e.g., update_draft_purchase_order) as the follow-up path, so it is strong context rather than full routing 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 useful context about what a call returns (header fields, line items), but says nothing about permissions, rate limits, or the behavior of the sparse-field selector.

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 names the resource, scope, and returned content, followed by a short endpoint reference. Tight overall, though the raw GET path is partly redundant with 'by id' and the enumerated field list is dense.

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 by listing header fields and line items, which is adequate for a read tool. The remaining gap is the undocumented `fields` selector behavior, which the agent cannot infer from schema or description.

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 only 50%: purchase_order_id carries a description while the `fields` parameter has none anywhere. The description's 'by id' merely restates the required parameter and does not explain that `fields` is a sparse-fieldset selector (pattern/maxLength of 2000), so it fails to compensate for the coverage gap.

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

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

States a specific verb (get) plus resource (one purchase order, transfer or assembly order by id) and enumerates the payload contents (header fields and line items). 'One ... by id' implicitly but clearly separates it from the sibling list_purchase_orders, and the scoping to a single document separates it from the connection/stock-update siblings.

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

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

Usage is implied rather than stated: 'by id' tells the agent a purchase_order_id is required, which implies you must already know the id (likely from list_purchase_orders). There is no explicit when-to-use, when-not-to-use, or named alternative for fetching related resources like connections or stock updates.

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 bar is lower, yet the description adds real value: it discloses the return shape (per-connection status values success/error/run/queued, save_po flag, external id and reference). It also restates read-only, consistent with annotations.

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

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

Front-loaded with the core purpose, followed by return-field detail and the endpoint. Dense but every clause earns its place; only slight redundancy in restating the read-only nature already implied by annotations.

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

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

With no output schema, the description compensates well by enumerating the returned status values and flags, which is exactly what an agent needs to interpret results. Missing only explicit guidance on when to prefer this over sibling retrieval tools.

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

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

Schema description coverage is 100% with a single well-documented purchase_order_id, so the schema carries the semantics. The description adds nothing about the parameter beyond echoing the endpoint's {id} placeholder, so the baseline of 3 applies.

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

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

States a specific verb and resource (get purchase order connections) and immediately clarifies what 'connections' means: whether/how the PO was saved to connected systems like ERP or accounting. This clearly distinguishes it from siblings such as get_purchase_order or list_purchase_orders.

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

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

The description implies the use case (checking sync status to connected systems) but never states when to use this versus get_purchase_order or get_purchase_order_stock_update. No explicit alternatives or exclusions are named, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, and the description reinforces that with 'Read-only: nothing is pushed.' More valuably, it discloses the shape of the returned data (per-warehouse items with stock_before, delta, error), which is not captured anywhere else since there is no output schema. This goes beyond the annotations.

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?

Compact and front-loaded: the payload description comes first, followed by the parameter nuance, safety note, and endpoint. Slightly awkward phrasing ('The stock updates a purchase order has computed') costs a point, but there is 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 explaining the return payload, and it does so at a useful level (per-warehouse items with three named fields). The safety profile is covered by annotations, and both parameters are documented, so the definition is adequate, though a bit more on response grouping or limits would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the for_destination behavior, but the schema's own description is actually more precise (it includes the default of true), so the description adds no meaning beyond what the schema already provides.

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 computed stock updates for a purchase order, broken down per warehouse with named fields (stock_before, delta, error). This is clearly distinct from siblings like get_purchase_order or list_purchase_order_items, so an agent can route correctly without opening other schemas.

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 (preview computed stock updates before pushing anything) but never states when to choose this tool over get_purchase_order or list_purchase_order_items, nor any prerequisites. The for_destination sentence is parameter guidance, not tool-selection guidance, so usage remains merely implied.

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 default field set and the underlying HTTP endpoint, which is useful context but does not go beyond 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?

A single front-loaded sentence carries purpose, the `fields` semantics, and defaults, followed by the endpoint. No waste.

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

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

No output schema exists, but the default field list gives the agent a good sense of what is returned, and annotations cover the safety profile. Minor gaps only, such as whether non-default fields can be requested beyond the named defaults.

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 50%: variant_id is documented in the schema, but `fields` is not. The description compensates by explaining `fields` holds 'the metrics named' and enumerating the default list, adding real meaning beyond the schema's bare pattern/maxLength.

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

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

States a specific verb (get) and resource (variant) with scope: 'One variant by its Inventory Planner id'. The singular framing distinguishes it implicitly from list_variants, though it never names the sibling explicitly.

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

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

Usage is implied by 'One variant by its Inventory Planner id' — fetch a single record when you have its id, rather than list_variants. However, there is no explicit when-to-use/when-not or named alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete response payload (cost_price, landing_cost_price, vendor_reference, vendor_name, vendor_packaging/MOQ, uom_ordering) and the underlying REST route, which is genuinely useful since there is no output schema. It stops short of documenting error behavior (e.g. unknown vendor_id) or currency/unit caveats on the cost 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 compact fragments: the resource statement, the field list, and the endpoint. It is front-loaded with purpose and wastes little, though the raw field-list dump and trailing URL are terse rather than elegantly structured.

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

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

With no output schema, the description carries the return-shape burden and does so by naming the returned fields, plus it exposes the REST path and the vendor_id format. For a simple two-parameter read this is nearly complete; only failure modes and pricing/unit semantics are 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?

Schema description coverage is 100% and both parameters are documented there, including the lowercase-vendor-name convention. The description restates the same vendor_id rule ('the vendor name in lowercase') without adding format, casing edge cases, or what variant_id accepts beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states the resource precisely ('One vendor's terms for a variant') and enumerates the fields returned, so an agent knows exactly what it gets. It implicitly separates itself from the list-style sibling by scoping to a single vendor, but it never names inventoryplanner_list_variant_vendors or inventoryplanner_get_variant as the alternatives, so sibling differentiation is left to inference.

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

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

Usage is implied rather than stated: the tool is clearly the singleton lookup once you already have a variant_id and vendor_id, and the schema notes vendor_id comes from inventoryplanner_list_variant_vendors. There is no explicit 'use this when X, use list_variant_vendors when Y' guidance or prerequisite/permission note in the description 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds useful content detail (the returned field set) and the REST path, but says nothing about pagination behavior, ordering of results, or what happens for an order with no items.

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 – resource plus field enumeration, then the endpoint path. It is front-loaded and each part earns its place, though the dense comma-separated field list reads as a run-on rather than a structured list.

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, enumerating the returned fields is exactly the compensation an agent needs, and the endpoint path aids orientation. What remains missing (pagination workflow, whether items can be filtered) is minor and partly covered by the page/limit schema entries.

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 75% (page and limit are documented in-schema). The description adds nothing about the page/limit/fields parameters and never explains the fields string syntax or that pagination uses next_page; the field list it enumerates is about return values, not inputs. Baseline 3 is appropriate at this coverage.

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 resource (line items of a purchase order) and lists exactly what each item contains (variant id, sku, title, quantities, cost, tax, discount, snapshots). This clearly separates it from sibling get_purchase_order (the order itself) and list_purchase_orders (the collection of orders).

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

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

Usage is only implied: the required purchase_order_id plus the GET path make it obvious you call this to read items of a known order. There is no explicit when-to-use statement, no guidance on preferring get_purchase_order first to obtain the id, and no exclusions or alternatives named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by disclosing the meaning of the `type` values and the default returned field set, but says nothing about pagination behavior, auth, rate limits, or the API's response envelope.

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 type semantics and filter example are front-loaded and the trailing endpoint citation is compact. The default-field list is long but earns its place since there is no output schema, so it isn't 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 helpfully enumerates the default returned fields and the meaning of `type`. Combined with a filter example and pagination parameters in the schema, an agent has enough to call the tool correctly; only sorting defaults and the relationship between `type` and the filter object are left implicit.

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

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

Schema coverage is already 80%, establishing a baseline of 3, and the description goes further by giving a concrete multi-key filter example with an operator suffix (`expected_date_lt`) and by documenting the values allowed in the `type` field, which the schema does not enumerate. It doesn't add anything about page/limit/sort beyond what the schema already documents.

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

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

States a specific verb and resource ('List stock orders') and clarifies that the resource spans three subtypes (purchase orders, transfers, assembly orders) with the exact `type` values that select them. It does not explicitly name a sibling such as get_purchase_order for single-record retrieval, but the list-vs-get distinction is evident from the name and description.

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

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

Usage context is present but implied: the filter example ({"status": "OPEN", "vendor": "Acme", "expected_date_lt": "2026-11-01"}) shows how to narrow results, and the `type` values show how to scope by order category. However there is no explicit when-to-use/when-not statement and no routing to alternatives like list_purchase_order_items when line-level data is wanted.

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 real behavioral context beyond that: removed variants are excluded by default unless include_removed is set, ~200 metrics exist, and the underlying endpoint is GET /api/v1/variants. No auth, rate-limit, or pagination-behavior detail is offered.

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

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

Front-loaded with purpose and then the single most important instruction (always pass `fields`), followed by defaults, field decoding, and filtering guidance. Dense but every parenthetical earns its place; 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 supplies the de facto return contract by listing the default fields and their semantics, plus the filter/sort vocabulary and the removed-variant default. An agent can call this correctly without opening 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 only 67% and `fields` and `include_removed` carry no schema descriptions at all; the description compensates by stating the exact default field set and decoding cryptic metric names (oos = forecasted days to sell out, under_value = forecasted lost revenue, replenishment = recommended order quantity). It also illustrates filter/sort usage, which the schema describes only generically.

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

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

States a specific verb (List) and resource (product variants) scoped to Inventory Planner's computed metrics, and enumerates the metric families (forecast, replenishment, days to sell out, lost revenue, etc.). It is clearly distinguishable from siblings like get_variant (single variant) and the purchase-order listing tools.

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

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

Gives concrete usage direction: 'Always pass `fields` to pick the metrics you need' and 'Use `filters` and `sort` for questions like which SKUs need reordering'. It does not explicitly name the sibling alternative (get_variant) for single-record lookups, so a 4 rather than 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 safety is covered. The description adds a useful enumeration of returned fields, which matters because no output schema exists, but it says nothing about pagination, ordering, or behavior when a variant has no vendors.

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

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

Two sentences, front-loaded with the resource and then the field payload, followed by the endpoint path. Dense but every clause contributes, and nothing is redundant with the schema or annotations.

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

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

For a one-parameter read-only list with annotations covering the safety profile, the description is nearly sufficient: it compensates for the absent output schema by naming the returned fields. Only list-level behavior (pagination, empty results, ordering) is unaddressed.

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

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

There is a single parameter (variant_id) whose schema description coverage is 100% ('Inventory Planner id.'), so the schema does the work. The description adds no format, sourcing, or lookup guidance for variant_id, which is the expected baseline at full coverage.

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 (the vendors a variant can be ordered from) and the returned fields, so an agent knows exactly what comes back. It does not explicitly contrast itself with the singular sibling inventoryplanner_get_variant_vendor, leaving the list-vs-single distinction to inference from the name.

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 inventoryplanner_get_variant_vendor (single vendor) or inventoryplanner_get_variant. Usage is only implied by the plural name; no exclusions, prerequisites, or alternatives are given.

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

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

Annotations give destructiveHint=true/idempotentHint=true/readOnlyHint=false but say nothing about scope. The description adds real behavioral detail beyond them: the order is read first, the call is refused unless status is 'draft', and the blast radius is bounded to three fields with no status change, no sending, no line-item or received-quantity mutation. That materially refines the agent's risk model.

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

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

Three tight sentences, front-loaded with the WRITE marker and the endpoint before any qualifiers. Every clause carries load: mutable fields, precondition, and exclusions. No filler.

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

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

For a 4-parameter mutation with no output schema, the description covers purpose, precondition, and mutation boundaries well. It stops short of saying what the call returns or whether partial success/field-level errors are possible, but nothing essential to invoking it correctly 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 50% (only expected_date and purchase_order_id are documented inline). The description compensates by enumerating the three writable fields — reference, expected date, notes — matching the optional properties and clarifying that other fields are not editable. It does not add format or constraint detail beyond the schema.

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

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

States a specific verb (WRITE: change), the exact resource (draft purchase order), and the three mutable fields, plus the HTTP verb and path (PATCH /api/v1/purchase-orders/{id}). It is immediately distinguishable from the create/get/list siblings, which either make new orders or read 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?

The precondition 'refused unless its status is "draft"' tells the agent exactly when this tool applies, and the exclusion list ('never changes the status, sends the order, or touches line items') steers away from adjacent operations. It does not explicitly name alternative tools (e.g. create_draft_purchase_order), so it falls short of a full routing statement.

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