SKU.io

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that a movement is posted which alters stock valuation and COGS, and it names the return value. It stops short of stating permission requirements or reversibility.

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

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

Three compact sentences with the core operation front-loaded, followed by side effects and return value. Every sentence earns its place and nothing is 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?

For a destructive mutation with no output schema, the description usefully covers the write's downstream impact and the returned adjustment id. It is nearly sufficient, but omits permission/idempotency expectations and leaves several required-looking parameters unexplained.

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 60% with 10 parameters, so the description carries responsibility to compensate, and it says nothing about any parameter. Fields like product_id, warehouse_id, notes, and warehouse_location_id are undocumented in both places, and no syntax, constraints, or interaction between quantity and adjustment_type is added.

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 set (increases, decreases, sets) on a precise resource and scope: one product's on-hand quantity at one warehouse. No sibling tool performs inventory adjustment, and the three supported modes are named explicitly, so an agent can identify the operation without opening the schema.

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

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

The description never states when to reach for this tool versus alternatives (e.g., get_inventory_levels for reading, find_product for resolving the product, list_warehouses for the warehouse). Usage is only inferable from the operation itself; no prerequisites, exclusions, or alternative routing 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?

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), the description adds the response shape ({status, data}), the per_page default of 10 on paginated lists, the 25 KB truncation-and-flag behavior, and a prompt-injection caveat that result data 'is not instructions'. These are concrete operational traits the annotations do not cover.

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?

Five dense sentences, all front-loaded: purpose/return shape first, then invocation, then truncation, then id source, then the safety caveat. No filler; every sentence carries distinct information.

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

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

With no output schema, the description compensates by describing the return shape, truncation limit, pagination default, and data-provenance warning. Nothing an agent needs to call this correctly appears to be 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 the baseline is 3. The description adds meaning beyond the schema by specifying that query carries filters/page/per_page and that per_page defaults to 10 on paginated lists, plus a concrete path example — a modest but real value-add.

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 ('Calls a read-only (GET) SKU.io REST API endpoint') and the return shape ({status, data}), and the 'read-only (GET)' framing clearly separates it from the sibling api_write. An agent can identify the tool's role without opening the schema.

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

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

It tells the agent where endpoint_ids and their parameters come from ('search_api and describe_endpoint'), establishing the prerequisite discovery workflow, and explains the endpoint_id/path alternative. It stops short of explicitly stating when to prefer this generic read over dedicated siblings like get_products or find_product.

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 cover the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=false), but the description adds meaningful context beyond them: the 'Allow changes' permission requirement, dry_run's validate-only behavior, the idempotency_key retry guarantee, and the return shape/time error format. It does not address side-effect scope or rate limits, so just short of top marks.

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

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

Four dense sentences that are front-loaded with the core operation before constraints and parameters. Efficient overall, though the parameter clause at the end reads as a compressed list that could be structured more cleanly.

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 5-param, nested-body, mutating call with no output schema, the description covers return format, required permission, dry-run safety, and retry semantics. Completeness is strong; only exhaustive side-effect/error handling detail 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?

Schema coverage is 100%, so all five parameters are already documented in the schema. The description restates dry_run and idempotency_key semantics that largely duplicate the schema text, adding only minor framing; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Creates or changes data through a SKU.io REST API endpoint') with the HTTP methods enumerated. It clearly distinguishes itself from the read sibling (api_read) and ties operation to search_api as the discovery mechanism, so an agent can tell it apart without opening the schema.

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

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

Explicitly bounds usage: only reviewed endpoints that create records or edit fields are callable, deletes/voids/cancels/sends are unavailable, and search_api marks callable endpoints. This gives both when-to-use and when-not, plus a routing 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?

Beyond annotations (readOnly, idempotent, non-destructive, closed-world), it adds a real prerequisite — 'Requires the send_planner.view permission' — and, in the absence of an output schema, discloses the exact figures returned (units per network, units short, SKUs short, units left at source, stockouts before arrival, 2-day reach). It does not mention result size limits or failure behavior, keeping it below a 5.

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

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

Three tight sentences, front-loaded with the operation and scope, then the filter, then the permission requirement. The metric list is dense but every item carries information the agent cannot get from structured fields.

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 comparison tool with no output schema, the description supplies the missing return-value picture, the cardinality limit, the optional filter's semantics, and the permission gate. Nothing an agent needs to select and invoke it 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?

Schema description coverage is 100%, so both parameters are already documented, and the description mostly restates the schema's constraints ('one to four', 'base plan first'). The phrase 'across the plans' slightly sharpens product_id's scope, but that is a marginal addition over the schema text.

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 opens with a specific verb and resource: 'Compare one to four send plans side by side,' and enumerates the compared metrics, so the agent knows exactly what the tool produces. It does not explicitly name a sibling it is not (e.g., get_send_plan for a single plan detail, explain_send for narrative explanation), leaving differentiation partly implicit.

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

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

It gives concrete context for the typical call ('the working plan and its scenarios') and explains the optional filter's purpose ('Pass product_id to compare a single product across the plans'). It stops short of stating when to prefer this over get_send_plan or explain_send, so there are no explicit exclusions.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds the return payload (product id, SKU, sku_url), which is genuinely useful given there is no output schema. However, it says nothing about the irreversible write, the dry_run validate-only path, or idempotency behavior, so behavioral disclosure is thin 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?

Two dense sentences, front-loaded with the operation and scope, followed immediately by the return contract. No filler, no redundancy.

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

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

For a 15-parameter create tool with no output schema, covering the return values is a good move, and annotations carry the safety flags. Still missing: any hint that dry_run and idempotency_key exist and matter, and any routing against the other create_* siblings. Usable, but not complete for a mutation of this size.

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 60%, in the middle band, and the description merely restates a handful of schema keys (SKU, name, barcode, cost, price, weight, suppliers) without adding formats, constraints, or defaults. It does not compensate for the ~40% of parameters (images, attributes, brand_name, idempotency_key, dry_run) that lack schema descriptions. Adequate, but not additive.

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 ('Creates one catalog product') and scopes it as a single item, which separates it from the read/update siblings like get_products, search_products, and update_product_pricing. It also enumerates the payload contents (SKU, name, barcode, cost, price, weight, supplier links). It stops short of naming an alternative tool, so it is clear but not explicitly differentiated.

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 when-to-use guidance, no prerequisites, and no mention of the notable alternatives or modes available to the caller (dry_run validation, idempotency_key replay) even though those appear in the schema. The agent is left to infer that this is the right tool for creating a single catalog product.

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

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

Annotations declare the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=false), and the description adds genuinely useful context on top: it is a draft only and nothing leaves the system, which is consistent with openWorldHint=false. It also pre-empts the missing output schema by stating the return payload (id, number, sku_url). It does not, however, reconcile the draft-only framing with destructiveHint=true.

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 sentences: the draft scope is front-loaded, the 'nothing is sent' guarantee follows immediately, and the return values close it out. No filler or restatement of the title.

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

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

For a 14-parameter mutation with no output schema, the description covers the draft semantics and return values but is thin on the mechanics the schema does not spell out, such as the dry_run vs idempotency_key interaction and the dropship exception on destination_warehouse_id. It is serviceable but not complete for the tool's complexity.

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?

With 14 parameters and 64% schema description coverage, the schema does most of the work and the description adds only a high-level grouping (supplier, warehouse, lines, charges) that maps to existing parameters. No format, dropship, or dry-run detail is added beyond the schema, so this is baseline-adequate rather than compensating.

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?

Names a specific verb (creates) and resource (draft purchase order) and enumerates the main payload parts: supplier, receiving warehouse, lines and charges. It is clear what the tool does, but it never distinguishes itself from siblings such as submit_purchase_order or create_sales_order, which a 5 would require.

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?

'Nothing is sent to the supplier' hints at a two-phase draft-then-submit flow, but the description never names submit_purchase_order or states when to prefer one over the other. There is no explicit when-to-use or when-not-to-use guidance, leaving the agent to 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 this is a non-readonly, destructive, non-idempotent operation, so the safety profile is covered. The description usefully adds the return fields (order id, number, status, sku_url) in the absence of an output schema, and mentions the draft mode, but says nothing about permissions, irreversibility of creates, or how the idempotency_key interacts with the declared idempotentHint=false.

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 sentences, action front-loaded followed by return value. No wasted words.

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 10-parameter destructive mutation with a 60% schema coverage and no output schema, return values are covered in the description, but required-field prerequisites, mode selection, and the interrelationship of idempotency with the non-idempotent annotation are left unaddressed.

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

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

Ten parameters at 60% schema coverage; the description adds only the loose notion of 'draft or with line items', which maps indirectly to order_status and sales_order_lines. It does not clarify required fields (order_status, order_date, currency_code) or any of the four undocumented parameters.

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 ('Creates a sales order') and adds scope detail about draft-vs-line-item modes. It does not differentiate from siblings like create_purchase_order or create_product, but the core purpose 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?

No when-to-use guidance, no prerequisites (e.g. account/currency requirements), and no mention of alternatives such as create_purchase_order. The only hint is the implicit 'draft needs no lines' mode, which is not framed as 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=false and destructiveHint=true, so the write/safety profile is conveyed structurally. The description adds the return value ('Returns the view id') and the favorite/default optionality, but it never explains why a create operation is flagged destructive nor any auth or permission requirements, so it contributes only modestly 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?

Two compact sentences with no filler; the purpose is front-loaded and the return value, useful given there is no output schema, is placed last where it belongs. The parenthetical list is dense but earns its space.

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 an 8-parameter mutation tool with no output schema, the description covers the core purpose and return value adequately, but leaves the destructive annotation unexplained and provides no when-to-use context. An agent could call it correctly, but with notable remaining gaps.

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 50% (model, dry_run, query_data, idempotency_key documented). The description restates the query_data contents as '(columns, filters, sort)' and alludes to favorite/default flags, but says nothing about model, is_shared, dry_run, or idempotency_key, so it adds little beyond the schema's own text.

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 ('Saves a named view') with the view's contents (columns, filters, sort) and scope (one data table). It is unambiguous what the tool creates, though no sibling tool overlaps this space so no explicit differentiation is needed.

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 versus alternatives, prerequisites, or what conditions warrant creating a saved view. The clause 'optionally as the user's favorite or default' hints at intent but never states a when/when-not 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=false and destructiveHint=true, so the write nature is known. The description adds real value beyond that: it clarifies the artifact stays unpublished and is never enabled or run, and it discloses the return payload (workflow id, validation, sku_url) despite there being 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?

Three tightly packed sentences with zero filler, and the core action plus its scope limit are front-loaded before the return-value note. Every sentence 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?

For an 8-parameter mutation tool with no output schema, the description covers the key behavioral constraints (draft-only, never executed) and enumerates what it returns, closing the output-schema gap. Only the pivot semantics of idempotency/preview_mode 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 description coverage is 75%, so the schema largely documents the parameters itself. The description only names 'nodes, edges' as the graph, which the schema already describes in detail, and adds no meaning for dry_run, preview_mode, category, or idempotency_key. Baseline 3 is appropriate.

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

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

States a specific verb and resource (validates a workflow graph and saves it as an unpublished draft) and explicitly bounds the scope with 'it never publishes, enables or runs it.' An agent can immediately tell this is a draft-only creation tool, distinct from any publishing or execution action.

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 negative scoping ('never publishes, enables or runs it') implies this is the drafting step rather than the publish/run step, which gives some guidance. However, no alternatives or siblings are named and no explicit when-to-use condition (e.g., vs. dry_run validation only) is stated, so usage is implied rather than directed.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it is a lookup that reports scope/role requirements and 'whether this connection may call it', i.e. it performs a permission check rather than any API call. It stops short of mentioning errors, rate limits, or caching.

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: purpose first, then the enumerated return contents. The enumeration is dense but everything listed is useful for a tool with no output schema. The 30+ word tail is long for one sentence but not padded with 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 the response, and it does so thoroughly: method, path, summary, description, path/query parameters, request-body rules, an example body, required scope and role permissions, pagination notes, and callability for this connection. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and the schema already provides the example value 'post.inventory-adjustments', so the baseline is 3. The description adds provenance the schema lacks - the id must come from search_api - which is genuine extra meaning for the caller.

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 ('Describes one SKU.io REST API endpoint') and names the exact key it operates on ('by its endpoint_id'). It also ties itself to the sibling that supplies that key ('from search_api'), letting an agent distinguish it from search_api and the api_read/api_write family without opening a 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 phrase 'by its endpoint_id from search_api' establishes the workflow: first find endpoints, then describe one. However, it never explicitly states when to use this instead of the raw api_read/api_write tools or what to do when endpoint_id is unknown; the routing is implied rather than spelled out.

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

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

Annotations already fully declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The one addition, 'runs no new diagnosis,' is genuinely useful because it warns the agent results may be pre-existing/stale. Still, there is no disclosure of pagination behavior, result caps, or what an undiagnosed listing looks like.

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

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

Two compact sentences with zero filler, front-loading the core action and return content before the read-only constraint. Every clause carries weight.

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

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

With no output schema, the description usefully sketches the return shape (per-listing tier plus diagnosis codes). The remaining shortfall is operational detail: six parameters with no explanation of paging or the undiagnosed filter, which matters for correct invocation.

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%, so page, per_page and filter_undiagnosed are undocumented in structured fields. The description partially compensates by naming the tier vocabulary (POOR, FAIR, GOOD), which supplies the enum values missing from filter_tier, but it says nothing about paging or what filter_undiagnosed selects, leaving real gaps.

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

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

States a specific verb and resource ('Lists one TikTok Shop integration's listings') plus what comes back ('quality tier (POOR, FAIR, GOOD) and the diagnosis codes'). No sibling deals with TikTok listing quality, so differentiation is implicit rather than stated, which keeps it from 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?

'Read-only; runs no new diagnosis' implies this is for reading existing diagnosis state rather than triggering a refresh, which is a useful when-to-use signal. However, it names no alternative tool for actually running a diagnosis and gives no conditions or exclusions beyond that one clause.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the result is a decomposed attribution (CPC, conversion, mix, price), it can be enriched with matched ERP causes, and the agent must quote the returned numbers rather than recompute them — a real constraint on downstream behavior. It does not describe pagination or empty-result behavior, but for a read-only analytics call that is a minor 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 sentences, zero filler. The metric scope and the output decomposition are front-loaded, and the quoting directive lands last where it will be read as an instruction on using the result.

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 eight optional parameters and no output schema, the description does the important work of saying what the response contains (effect breakdown plus ERP causes) and how to use it (quote, don't recompute). The main remaining gap is the interaction between the two period parameter pairs, which an agent must infer from the schema 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%, with every parameter documented including defaults (acos, yesterday, 7 days ago, prior period). The description only reinforces that the tool operates across two comparable periods, which hints at how date_from/date_to interact with compare_from/compare_to but does not explain the pairing logic or the effect of supplying compare_to without compare_from. Baseline 3 is appropriate.

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

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

The description names a specific analytical operation (explaining a movement in ACoS, spend or sales between two periods) and enumerates the decomposition it returns: CPC, conversion, mix and price effects plus ERP causes. That is well beyond a restated title and clearly separates it from data-retrieval siblings like get_ad_performance. It stops short of naming a sibling to use instead, so a 4 rather than 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?

Usage is implied by the causal framing: call this when you need to know why a metric moved, rather than what it was. There is no explicit when-not guidance, no mention of what to do when no ERP causes match, and no pointer to get_ad_performance or get_ad_health as the alternatives for raw numbers or anomaly detection.

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 read-only/idempotent/non-destructive, and the description adds substantial context on top: what the response contains (both sides, difference history and its start date, on-hand by source, open allocations, findings with units and evidence plus a suggested fix) and the exact finding taxonomy. The permission requirement is also disclosed, which annotations do not cover.

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 first clause, followed by return contents and the finding taxonomy. The long enumerated findings list makes it a single dense sentence, but each item is informative enough to earn its place; light restructuring would improve it.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: both sides of the comparison, difference history, source breakdown, allocations, and structured findings. Together with the permission note and the closed-world/read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both 'sku' and 'warehouse' are already documented in the schema, including the optionality rule for warehouse. The description adds only the framing 'one product at one 3PL warehouse', which the schema already conveys; baseline 3 applies when the schema carries parameter meaning.

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 precise verb ('Explain why ... differs') with a fully scoped resource: one product, one 3PL warehouse, SKU.io on-hand/available vs. the 3PL, sourced from the latest inventory comparison. This clearly separates it from reporting siblings like get_inventory_levels and from the mutating adjust_inventory.

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 clear context for invocation ('from the latest 3PL inventory comparison', 'one product at one 3PL warehouse') and flags the required inventory.index permission. It stops short of naming alternatives (e.g., use get_inventory_levels for raw numbers, adjust_inventory to fix) or stating when not to use it.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety bar is low; the description adds genuine value beyond them by naming the required send_planner.view permission and describing the returned analysis content. Since there is no output schema, this disclosure of return structure is doing real work, though it omits any indication of latency or size of the response.

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, followed by a dense but well-grouped catalogue of what the explanation returns, then short operational sentences. The middle clause is long and list-heavy, but every element maps to actual output content rather than filler.

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

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

With no output schema and no annotations covering return values, the description fully carries that burden by naming each section of the explanation, including as_of and reach before/after. Permission requirements, parameter alternatives, and default send_plan behavior are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description echoes the sku/product_id alternative and supplies adapter-key examples for network, but adds no syntax, format, or edge-case meaning (e.g. what happens when network matches nothing) beyond what the schema states, 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 ("Explain why the send plan sends what it does for one product") and enumerates exactly what the explanation contains: velocity × days math, network recommendation deltas, lanes, and 2-day reach. This clearly distinguishes it from get_send_plan (which retrieves a plan) and explain_inventory_gap (which targets gaps).

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 clear context for use (diagnosing the reasoning behind one SKU's send plan) and stipulates identification by sku or product_id plus an optional network filter. It does not explicitly say when to prefer it over get_send_plan or explain_inventory_gap, so a routing exclusion is missing, but the operating context is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description only needs incremental value — and it supplies the return payload ('id, SKU, name and sku_url'), which matters because no output schema exists. It stops short of describing match-count behavior or how conflicting keys are resolved.

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 sentences with zero filler; the lookup modes are front-loaded before the return-value note. Every clause carries information the 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 5-parameter lookup tool with no output schema, the description covers both the input keys and the returned fields, which is most of what an agent needs. It leaves minor gaps: no mention of the limit/pagination behavior for q, and no statement of what happens if multiple keys are supplied.

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 40% (q, id, sku, limit carry no descriptions), and the description compensates by mapping each lookup key to its semantics: sku=exact SKU, code=barcode, id=product id, q=fuzzy text search. That distinguishes exact-match keys from the fuzzy one, which the schema alone does not convey.

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 ('Finds a product') and enumerates the four lookup modes with their parameter names, so the agent knows exactly what the tool retrieves. It does not differentiate itself from close siblings like search_products or get_products, which is the only thing keeping it from 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?

'Give one of them' is an explicit invocation constraint that tells the agent the lookup keys are mutually exclusive and one is required, even though the schema marks nothing as required. However, there is no when-to-use guidance against siblings such as search_products/get_products, so the routing decision 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 declare readOnlyHint/idempotent/non-destructive, so the trailing 'Read-only' adds nothing. Beyond that, the description discloses meaningful behavior: results are ordered worst first, each row carries open guardrail signals with reasons, cover days, next inbound PO, POAS with 1.0 = break-even, ACoS vs break-even, and what SKU.io has paused or throttled. With no output schema, that result-content disclosure is genuinely useful.

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 with the purpose front-loaded before a colon-delimited field list; every clause carries information. It borders on over-packed, but nothing is redundant.

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 read tool with no output schema, the description covers purpose, ordering, and returned content well, and annotations cover the safety profile. It still leaves the agent without sibling routing guidance and without explanation of the health/signal_type filter vocabulary or default result limits.

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 sku, limit, health, platform, product_id, signal_type, and only_with_signals, making 3 the baseline. The description adds no filter semantics beyond what the schema states and does not clarify the default behavior of only_with_signals (implicitly true from 'open guardrail signals') or how filters interact.

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

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

The description states a specific resource and angle: advertised products whose ads waste money on stock or margin, ranked worst first, with named output fields (POAS, ACoS vs break-even, cover days). That is far more specific than the name 'get_ad_health' alone. It does not explicitly distinguish itself from siblings like get_ad_performance or get_ad_recommendations, 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?

The 'worst first' framing and 'waste money' scope imply a triage use case, which is useful implied guidance. However, it never says when to use this instead of get_ad_performance, get_ad_recommendations, or explain_ad_change, and offers no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the closing 'Read-only' is largely redundant. The description does add useful metric semantics (POAS 1.0 = break-even, break-even ACoS) that go beyond annotations, but says nothing about pagination, truncation, or behavior when no ad platform is connected.

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 that front-loads the metric set and ends with the read-only note. It is efficient, though the long parenthetical-free run of metrics makes it slightly list-like rather than prioritized.

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 analytics tool with a fully documented schema and explicit annotations, the description covers the metric meaning and breakdown options an agent needs. Missing only edge-case behavior (empty results, unconnected platforms), which is minor given the annotation and schema richness.

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 seven parameters are already documented in the schema, including defaults and the platform/group_by value lists. The description echoes the grouping options and break-even ACoS but adds no syntax or interaction detail (e.g. how platform interacts with group_by) beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (ad performance across connected ad platforms) and enumerates the exact metrics returned (spend, attributed sales, ACoS, ROAS, TACoS, POAS, blended POAS, contribution after ads) plus the supported breakdown dimensions. This clearly separates it from siblings like get_ad_health, get_ad_recommendations, and get_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 usage via the date range and grouping options, but it never says when to choose this over get_ad_health or explain_ad_change, nor does it state prerequisites such as needing a connected ad platform. Usage is inferable but not explicit.

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 this is a read-only, idempotent, non-destructive list operation, so the safety profile is covered. The description adds only that the listed items carry reasons attached; it says nothing about ordering, whether the three lists are truncated by the shared limit, or what happens when a filter matches nothing.

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 enumerates the three payload categories with no filler. It is efficient, though the fragment form leaves the aggregation behaviour (three lists in one response) implicit rather than stated.

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, zero-required-parameter list tool this is close to adequate, and there is no output schema to explain. However, the description never clarifies that three distinct result lists are returned or how limit and the ID filters interact across them, which an agent needs to interpret the response correctly.

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

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

Schema coverage is 100% and each of the three optional parameters is documented in the schema itself, including the default of 20. The description adds no 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?

The description names the three concrete resource types (ad change sets awaiting approval, goal suggestions, open anomalies) and their common thread (each with its reason), which is far more specific than the title alone. It does not name or distinguish itself from nearby siblings like get_ad_health, get_ad_performance or explain_ad_change, so it falls 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?

There is no explicit when-to-use guidance: nothing says to call this before propose_ad_changes, or to prefer explain_ad_change for a single item's rationale. The reader must infer the use case from the enumerated content types, and no exclusions 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 already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes further by disclosing the required permission (send_planner.view), the 548-day ceiling, the 90-day default window, and the provenance caveat that figures are estimated from daily per-node stock rather than the marketplace promise. It does not describe response shape beyond content, but with no output schema and rich annotations this is a strong addition.

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

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

The core definition is front-loaded in the first clause, and every sentence carries content. The second sentence is dense, stacking the range cap, default, and permission requirement into one string, which is efficient but slightly overloaded.

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 7 optional-leaning parameters, no output schema, and a moderate analytical surface, the description covers the essentials: what is measured, the window bounds and default, data provenance, and the permission gate. Remaining gaps (how product_id relates to sku, exact response granularity) are minor and largely covered by 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 already 86%, so the baseline is 3; the description still adds real meaning by clarifying that omitting SKU yields the whole network and by pinning down the date-window semantics ('up to 548 days; defaults to the last 90'). It does not clarify how product_id, destination_warehouse_id, or send_plan_id interact, but the schema documents those.

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?

Names a specific metric (estimated 2-day reach over time), the entity scope (one SKU or the whole network), and the unit of measure (weekly % of buyers within ground reach of an FC/warehouse holding sellable stock). An agent can distinguish this from siblings like get_send_plan or explain_inventory_gap without opening the schema.

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

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

Usage is only implied by the description of what is returned (a historical trend, not a point-in-time snapshot). The clause 'not the marketplace delivery promise' disambiguates the data source but not tool selection. There is no explicit when-to-use, when-not-to-use, or named alternative sibling.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that: it enumerates the returned quantities (available, reserved, total, in-transit) and discloses the on_order semantics including overdue flagging for passed PO dates.

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, zero filler, and the core purpose is front-loaded before the return details. Every clause adds either scope or return semantics.

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 describe returns itself, and it does so thoroughly (quantities per warehouse plus on_order with PO dates and overdue flag). Nothing essential for calling the tool 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 description coverage is 100%, so both parameters (product_id, warehouse_id) are already fully documented, and the description only restates that warehouse filtering is optional. Baseline 3 applies since the schema carries the parameter burden.

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 ('Get inventory levels for a product') and immediately scopes it ('optionally filtered by warehouse'). The explicit return contents (per-warehouse breakdown, on_order) make it unmistakably distinct from siblings like adjust_inventory or get_stockout_risk.

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 via 'optionally filtered by warehouse' but gives no when-to-use guidance, no prerequisites, and never points to an alternative. An agent has no help choosing between this and get_stockout_risk, get_products, or adjust_inventory.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that results are silently capped to the last 90 days even when a wider range is requested — but says nothing about ordering, default page size, or result format.

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

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

Two short sentences with zero filler, and the most important operational constraint is front-loaded. It is perhaps too terse for a 4-parameter tool, but nothing is wasted.

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 list tool whose annotations carry the safety profile and whose schema fully documents parameters, the description covers the key constraint but omits default limit behavior, result ordering, and how it relates to sibling order tools. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all four parameters (limit, toDate, fromDate, orderNumber) are already documented in the schema, and the date-range capping is stated there too. The description repeats the 90-day constraint but adds no syntax or semantics beyond what the schema provides, making the baseline 3 correct.

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

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

States a clear verb and resource ('Get orders from sku.io system'), so the agent knows it retrieves sales orders. However, it never distinguishes itself from closely-named siblings like get_order_status or search_purchase_orders, so sibling differentiation is missing.

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 guidance and names no alternatives among the many sibling retrieval tools (get_order_status, get_purchase_order_details, search_products). The only constraint offered is the 90-day window, which is a limit rather than usage 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds value beyond that by enumerating the returned fields (status, fulfillment status, line count, totals) in the absence of an output schema. It stops short of describing behavior for a nonexistent order number, which would have earned 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?

One sentence, front-loaded with the action and keyed parameter, ending with the return payload. Every clause carries information and nothing is redundant.

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 lookup with complete annotations and no output schema, the description covers what the tool needs: the key, the action, and the shape of the result. The only meaningful omission is what happens when the order number isn't found.

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 with 100% schema description coverage, so the schema already explains order_number. The description only reinforces it via "by its order number" without adding format, length, or accepted-variant details beyond the schema; 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 ("look up a sales order") and enumerates what comes back (status, fulfillment status, line count, totals), so the agent knows exactly what the call yields. It doesn't explicitly distinguish itself from the sibling get_orders (list) or get_purchase_order_details, but the single-order-by-number framing makes the scope 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 only implied: you call it when you already have an order number and want a point lookup. There is no explicit "use this instead of get_orders when..." guidance and no stated preconditions or failure behavior, which matters given several order-related siblings.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description usefully adds two behavioral facts beyond that: results are returned 'newest first' and the exact field set returned. It says nothing about pagination defaults or result limits, which is the 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?

A single sentence that front-loads the verb, resource, and scope, then layers ordering and filtering without a wasted word. Nothing could be cut without losing information.

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

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

With no output schema, the description sensibly enumerates the returned fields and the sort order, which is what an agent most needs. It falls short only on pagination behavior for the page/per_page params, a minor omission for a simple read-only list tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the name/SKU filtering that the schema already documents and adds no syntax, matching, or partial-match semantics, and it ignores the page/per_page parameters entirely.

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 sku.io products) and enumerates the returned fields (id, SKU, name, barcode, type) plus the sort order. It is clear on its own, but it never differentiates itself from the closely-related siblings search_products and find_product, which the filter-by-name/SKU wording makes even more ambiguous.

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 'optionally filtered by name or SKU' hints at a browse-with-filter use case, but the description names no alternative and gives no condition for choosing this over search_products or find_product. An agent has no stated when-to-use or when-not-to-use 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, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds meaningful payload context by enumerating the returned sections (lines, supplier, warehouse, shipments, totals), which matters because there is no output schema. It omits not-found/error behavior.

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

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

A single front-loaded sentence with no filler; the retrieval action and returned fields are stated immediately with zero redundancy.

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

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

No output schema exists, and the description partially compensates by listing the returned sections, while annotations cover the safety profile. Missing only edge behavior such as invalid identifiers or missing POs.

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 params are well documented in the schema itself. The description merely restates that a PO number or ID can be used, adding no format, precedence, or fallback detail beyond what the schema already says.

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 (look up) and resource (purchase order) plus the identifiers accepted and the payload returned (lines, supplier, warehouse, shipments, totals). It implicitly separates itself from search_purchase_orders (single-record lookup vs search), but never names a 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 only implied: the agent can infer this is for fetching one known PO by number or ID. There is no when-to-use/when-not guidance and no pointer to search_purchase_orders for list-style queries, so routing between the two 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that the list includes a filing deadline (a time-sensitivity signal), but says nothing about result ordering, pagination totals, or what 'in full' includes beyond the listed 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?

A single front-loaded sentence with zero filler; the list mode is stated first and the id-mode exception follows. Nothing is repeated from annotations or 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?

With seven parameters, no output schema and no enum constraints, the description usefully substitutes by enumerating the returned fields (status, category, amount, deadline). It stops short of explaining pagination behavior or result ordering, which matters for a paged list endpoint whose page/per_page semantics live only in 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 86%, so nearly every parameter is already documented in the schema, and the description only reinforces the id mode. It adds no meaning about how filter_search or filter_due_within_days combine, which is the one gap the schema leaves open (no filtering semantics are disclosed).

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?

Names a specific verb and resource (lists Amazon FBA reimbursement cases) and enumerates the returned fields, plus explains the alternate single-record mode keyed on id. It does not name or contrast any sibling tool, but none of the listed siblings covers reimbursements, so disambiguation is largely unnecessary.

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 clause 'returns one case in full when id is given' implicitly tells the agent how to switch modes, but there is no explicit guidance on when to prefer this tool over adjacent reporting tools, and no stated prerequisites or exclusions. Usage has to be inferred from the purpose statement.

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, idempotentHint and destructiveHint=false, yet the description still adds substantive behavior: the permission required (send_planner.view), the read-only limitation, the polling-until-ready workflow, and the ordering/capping of exceptions (up to 25, worst first). None of this is derivable from the structured 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?

The first sentence is a long but dense enumeration of return contents and each clause carries information; the remaining sentences front-load the default behavior and the polling case. Slightly heavy in a single sentence, but no filler and the primary instruction comes first.

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 must carry return-value disclosure, and it does so thoroughly while also covering auth requirements and the read-only boundary. Nothing an agent needs to call this correctly and interpret the response is missing.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3, but the description adds real meaning: what omission defaults to (latest ready working plan) and why you would supply an id (to follow an externally started plan, polling for status). This tells the agent more than 'The send plan id' alone.

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 a send plan') and then enumerates exactly what comes back: status, data as-of time, per-network totals (units, SKUs, cases, capacity), top exceptions, 2-day reach, and the 5 lowest-reach fast sellers. An agent can distinguish this retrieval tool from explain_send or api_read without opening the schema.

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

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

Gives explicit routing rules: omit send_plan_id to get the latest ready working plan, or pass an id to follow a plan started elsewhere and poll until 'ready' or 'failed'. It also names the boundary condition ('this server is read-only and cannot start a plan'), pointing the agent to the app or POST /api/send-plans for creation.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the risk model — available inventory plus inbound POs/transfers landing before runout, compared against daily average consumption and supplier lead times — which lets an agent explain how a result was derived. It omits sort order of results and any pagination behavior past the limit default.

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 it does, then the computation, then the invocation cue. No repetition of the title or filler wording.

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 should ideally indicate what a result looks like (product identity, days of cover, risk flag). It covers the inputs and the analytical logic well, leaving only the return shape implicit — a modest gap for an agent that must report results.

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

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

Schema description coverage is 100%, so all four optional parameters (limit, supplier_id, warehouse_id, days_threshold) are already documented with defaults. The description only echoes the notion of a day threshold and filtering scope without adding syntax, units, or interaction details, 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?

The description gives a specific verb and resource ('Find products at risk of stocking out') plus the time-window scope, which is distinct from sibling tools like get_inventory_levels and explain_inventory_gap. It never names a sibling to explicitly route against, which keeps it just 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?

'Use when users ask about stockout risk, low stock alerts, or which SKUs need reordering' gives clear user-intent triggers for invocation. There are no exclusions or named alternatives (e.g., when to prefer explain_inventory_gap or get_inventory_levels instead), so it stops at a 4.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: what each part actually returns and where field meanings live (fields.md in the JSON download). It omits error behavior for an unknown id, which keeps it from a 5.

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

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

Two sentences, no filler, with the core action front-loaded before the part semantics. The second sentence is dense and somewhat run-on, but every clause carries information the 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?

With no output schema, the description correctly steps in to describe both return shapes, which is the main completeness risk here. Given a simple two-parameter read tool and strong annotations, little else is missing beyond failure modes and whether findings are paginated.

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

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

Schema coverage is 100%, so baseline is 3, and the description goes beyond the terse enum ("findings" (default) or "pack") by explaining what each enum value yields. The report_id parameter is only covered by the schema's own pointer to list_support_insights_reports.

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 ("Read one Support Insights report by id") and the singular "one ... report" implicitly contrasts with the list_support_insights_reports sibling. It further decomposes the tool into its two returnable parts, so an agent knows exactly what it retrieves.

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 selection guidance between the two modes: "findings" for ranked findings/scope notes/verified facts, "pack" for the full evidence pack. It does not state any when-not-to-use condition or explicitly name the sibling list tool, but the context is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds genuine extra context: results are newest-first and, notably, that reports are computed by fixed rules rather than AI—useful provenance/trust information an agent cannot get from structured 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?

Two compact sentences: the first front-loads what is returned and the ordering, the second adds provenance. No filler or redundancy.

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

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

With no output schema, the description compensates by listing the returned fields (id, status, period, generated time, counts) and the sort order, and annotations cover the safety profile. Sufficient for an agent to call the tool correctly.

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

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

Schema coverage is 100% and the single 'limit' parameter is fully documented in the schema, including default and max. The description only reiterates the newest-first ordering, adding no syntax or constraint detail beyond structured data, so baseline 3 applies.

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

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

States a specific verb (List) and resource (this account's stored Support Insights reports) with scope and sort order, and enumerates the returned fields. The 'List' framing clearly contrasts with the singular sibling get_support_insights_report.

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

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

Usage is implied by the name and the 'List' vs 'get' sibling pairing, but the description never explicitly says when to use this versus get_support_insights_report or what conditions favor listing over fetching one report. Adequate but not spelled out.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world listing. Beyond that, the description discloses meaningful domain behavior: which warehouse categories are structurally ineligible to be PO destinations, and which flags the response carries. No output schema exists, so this disclosure genuinely adds value rather than repeating structured data.

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

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

Three sentences, front-loaded with the core purpose before the filter and the PO-destination rule. Every sentence carries information, though the type enumeration is duplicated verbatim from the schema and could be trimmed.

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 only one optional parameter, the description compensates well by naming the two decision-relevant response flags and their business implication for PO destination selection. It still doesn't say what the remaining warehouse fields look like, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% and the schema's own description already enumerates the accepted type values (direct, 3pl, supplier, amazon_fba, virtual). The description restates the same list and adds only the word "optionally". Baseline 3 is appropriate; the schema does the heavy lifting for this single parameter.

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 all available warehouses") plus the optional scope of filtering by type. There is no competing warehouse listing tool among the siblings, so the purpose is unambiguous and the agent can tell exactly what it gets.

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

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

It gives a concrete downstream usage rule: when resolving a purchase order destination, only offer warehouses where "can_be_po_destination" is true, and explains why supplier/Amazon FBA warehouses are excluded. It does not name an explicit alternative tool or say when not to call this, 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 declare readOnlyHint=false and destructiveHint=false but say nothing about the approval workflow. The description adds real value beyond them: no change is applied, approval happens manually in the SKU.io UI at a named location, and the call returns a set id, status and link. It omits idempotency behaviour despite an idempotency_key parameter, which keeps it from a 5.

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

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

Three short sentences with no filler. The scope and the proposal-only nature are front-loaded before the return-value note, so the most decision-relevant facts come first.

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 six-parameter tool with a nested changes array and no output schema, the description covers what it does, that nothing is applied, and what comes back (set id, status, link). The gaps are the unmentioned optional parameters (dry_run, summary, idempotency_key), which an agent would have to discover from the schema 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 50%, so the schema documents some parameters (reason, dry_run, idempotency_key, after, entity_type) while ad_account_id, summary and the changes array structure are undocumented. The description partially compensates by naming the four change kinds, which map onto the operation enum, but it never explains dry_run, summary, reason or the idempotency key, so the baseline 3 is appropriate.

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

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

States a specific verb ('Proposes'), enumerates the exact change classes (bid, budget, pause/enable, ad-rate) and scopes it to 'one ad account'. An agent can immediately distinguish this mutation-proposal tool from the read/explain siblings such as explain_ad_change, get_ad_recommendations or get_ad_performance.

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 sentence 'Nothing is applied: a person approves them in SKU.io under Advertising → Changes' gives the key usage context: this is a proposal-only path that requires human approval downstream. It does not explicitly name alternatives or state when-not to use it (e.g. when a change is already approved or when only explanation is wanted), 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 write, destructive, non-idempotent and closed-world, so the safety profile is largely covered. The description adds the return payload ("invoice id and sku_url"), which is useful since there is no output schema, but it omits permissions, side effects on the PO, and how dry_run/idempotency change behavior.

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

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

Two sentences, no filler, with the operation and its scope stated first and the return value second. Every clause carries information the 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 10-parameter destructive mutation it covers purpose and the return shape, which is more than many tools do. However it says nothing about preconditions, error behavior, or the dry-run/idempotency interplay, leaving real gaps for an agent invoking it unattended.

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?

With 70% schema description coverage, the schema already documents status, dry_run, idempotency_key, dates and the two line arrays. The description only loosely maps "lines and charges" to purchase_invoice_lines and financial_lines and adds nothing about due_date, currency_id, or which array carries what 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?

The description gives a specific verb and resource ("Records a supplier invoice (bill)") plus the scope constraint ("against one purchase order, with its lines and charges"), which is enough to distinguish it from create_purchase_order and record_vendor_credit. It does not explicitly name or contrast those siblings, so it falls 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?

It states a constraint (one PO per invoice) but gives no when-to-use context, no prerequisites such as the PO existing or being in a receivable state, and no guidance on choosing between this and the related record_vendor_credit tool. The agent must infer all routing decisions.

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/destructive profile, but the description adds real value by clarifying the effect scope: it lands as a draft for review and is not authorized or applied to a bill. It also names the return payload (id, number, sku_url), which no output schema covers. Minor gap: it does not reconcile its benign 'draft' framing with the destructiveHint=true annotation.

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 clauses, zero waste: the action and its draft status are front-loaded, the non-authorization caveat follows, and the return values close it out. Every element earns its place, especially the return payload given there is no 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 10-parameter mutation with no output schema, the description covers purpose, the non-applied effect, and return values, while annotations and a 70%-documented schema carry the rest. It is nearly complete; only the destructive/idempotency nuances and a few undocumented parameters are unaddressed.

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

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

Schema description coverage is 70% and 10 parameters exist; the schema already documents lines, dry_run, credit_date, credit_reason, currency_code, idempotency_key and vendor_credit_number. The description adds no parameter-level meaning (supplier_id, supplier_reference, vendor_credit_note are undocumented in both places), so it sits at the baseline rather than compensating.

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 ('Records a supplier credit memo as a draft vendor credit') with the crucial qualifier that it is a draft, not an authorized or applied credit. It does not explicitly distinguish itself from close siblings such as record_purchase_invoice, 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?

The scenario is implied ('supplier credit memo ... for review'), and the description usefully signals the record is unapplied pending review. However it names no alternative tool or condition for choosing this over record_purchase_invoice or adjust_inventory, and gives no prerequisites (e.g. what must exist first).

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/idempotent/destructive, so the description is free to add what the annotation cannot: the exact return payload (endpoint_id, method, path, summary, required scope) and the callable flag with a reason when the connection cannot call an endpoint. That callable/permission detail is genuinely behavioral context 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?

Two sentences, front-loaded with what the tool does and the intent-based framing, then the return shape and downstream wiring. No filler or repetition of the title.

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

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

There is no output schema, so the description correctly takes on the burden of describing return fields and the callable status, and it links results to the follow-up tools. It is essentially complete for a read-only search tool.

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

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

Schema description coverage is 100%, so limit and method are fully documented in the schema and the enum is self-explanatory. The description's example intents ('inventory adjustment', 'list purchase orders') do add some meaning for the query parameter, but not enough to exceed the baseline for a fully documented 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 (searches) and a precise resource (the SKU.io REST API reference) scoped by intent, with concrete examples of query phrasing. That clearly separates it from siblings like search_products or search_purchase_orders, which search data rather than the endpoint catalog.

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 example queries and explicitly routes the result forward: an endpoint_id found here works with describe_endpoint, api_read and api_write. It does not, however, state when to skip this tool or how it relates to search_products, so the when-not guidance is only 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: price filters are applied server-side, results carry default-tier selling price and attributes, and a no-match search returns near spellings rather than exact matches.

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 sentences, front-loaded with the core capability, then filters, then return contents, then fallback semantics. Each sentence carries information; 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?

With no output schema, the description usefully describes what matches carry (default-tier selling price, attributes) and the fuzzy-match fallback. For a read-only search tool this is nearly complete; result limits/pagination are the only notable omission.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces meaning ('min_price/max_price applied on the server', price compared against default-tier selling price) but adds little that the schema does not already state.

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 for products') and enumerates the searchable keys (SKU, name, barcode, ID, attribute value). It does not, however, distinguish itself from close siblings like find_product and get_products, which an agent will have to disambiguate on its own.

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 when you have a SKU/name/attribute to look up), and the fallback behavior is described. But no explicit when-to-use vs find_product/get_products, and no exclusion or prerequisite guidance is offered.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the fact that results are 'summary details' rather than full records, but says nothing about result limits, pagination, or empty-result behavior beyond what the schema 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?

Two short sentences that lead with the action and searchable fields, then the return shape and usage. Efficient overall, though the second sentence is mildly redundant with the first.

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-required-parameter read tool with no output schema, the description conveys the return contents, the searchable dimensions, and the empty-query default (via schema), while annotations carry the safety profile. Only the absence of any reference to sibling alternatives leaves a small 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%, with the query parameter spelling out the searchable fields and the empty-case listing behavior, and status enumerating every accepted value. The description's mention of 'PO number, supplier name, or status' merely echoes the schema, adding no syntax or matching semantics.

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 (purchase orders) and identifies the searchable fields plus the return shape ('summary details'). Implies it differs from get_purchase_order_details by returning only summaries, but never names that sibling, so the differentiation is inferred rather than explicit.

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

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

'Use this to find recent POs or look up specific ones' gives a use context, but there is no explicit when-not guidance and no routing to the obvious alternative get_purchase_order_details for full PO data. Usage is implied, not delineated.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the irreversible third-party side effect ('cannot be recalled') and the hidden state mutation (approving/opening a draft), which the annotations alone do not convey.

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 sentences with the core action front-loaded and the critical irreversibility warning placed last for emphasis. No filler or restatement of the title.

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

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

For a destructive, open-world mutation with no output schema, the description covers the action, the required pre-existing draft, and the non-recallable consequence. It leaves the required permissions and the result of a dry_run unstated, but annotations and schema carry the rest adequately.

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 five parameters (dry_run, idempotency_key, notify_supplier, supplier_message, purchase_order) are already documented. The description adds only a marginal hint ('e.g. by email') and does not elaborate on parameter behavior, so the baseline 3 is appropriate.

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

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

States a specific verb (Submits) and resource (one purchase order) plus its destination (to its supplier). It is clearly distinguishable from the sibling create_purchase_order and get_purchase_order_details, which operate on the draft/reference rather than sending it out.

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

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

Implies usage by stating it acts on an existing PO ('approving and opening a draft first'), which tells the agent a draft must exist. However, it never explicitly says when to use this versus alternatives like create_purchase_order or record_purchase_invoice, 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 disclose destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: 'Overwrites' conveys full replacement of existing tiers, 'Only price fields are sent' clarifies that non-price product fields are untouched, and it names the returned fields on a tool with 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?

Two tight sentences with no filler; the overwrite semantics and the price-only restriction are front-loaded, and the return-value note is tucked at the end where it belongs.

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 destructive mutation with full annotation coverage and complete schema documentation, the description covers the essential gaps: overwrite behavior, restricted field scope, and return payload (no output schema exists). It stops short of noting prerequisites like permissions or rate limits, but nothing critical to correct invocation 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 each of the five parameters is already documented, including the 'Omit to leave sell prices alone' behavior for pricing and the idempotency replay semantics. The description's 'and/or' hints at optionality of pricing vs suppliers but adds nothing the schema does not already state.

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

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

The description gives a precise verb ('Overwrites') and unambiguously scoped resource ('one product's sell-price tiers and/or supplier costs'), which is clearly distinct from siblings such as adjust_inventory or create_product. 'Only price fields are sent' further delimits the operation.

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 'Only price fields are sent' implies this is a partial pricing-only update and not a general product edit, which is mildly useful boundary guidance. However, it never states when to prefer this over alternatives, nor when to use dry_run or idempotency_key, leaving usage largely inferential.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful context by disclosing that a live token and its scopes are surfaced, which matters for an agent reasoning about credential exposure. It stops short of naming failure modes (e.g. invalid/expired token behavior).

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

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

A single sentence that front-loads the subject (what is returned) and carries no filler. Every clause adds a distinct returned field.

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 is the only source of return-value information and it covers the key fields (user, tenant, token, scopes). For a zero-param read-only identity probe this is nearly sufficient; only error/expiry behavior 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 of 4 applies; there is nothing for the description to disambiguate and it correctly avoids inventing any parameter discussion.

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 (returns) and enumerates the exact resources: the SKU.io user, tenant, token, and the token's scopes. No sibling tool covers identity/credential introspection, so it is trivially distinguishable from api_read, search_api, and the product/order 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?

The name and description make the intended use (verifying which identity and scopes back the current connection) strongly implied, and no alternative tool could serve that purpose. However, the description never states when to reach for it or any precondition, so guidance is only implicit.

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