PackIndex

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 description is free to add the behavior that matters: free callers are benchmarked against a 12-week delayed reference value, and quote_date comparison is a paid-plan feature. That plan-gating and data-freshness disclosure is exactly the kind of context annotations cannot express.

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

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

Two sentences, front-loaded with the user-facing question, then a single clause-rich sentence covering inputs, currency/unit flexibility, and each output. 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?

There is no output schema, so the description must describe returns, and it does: difference %, verdict, range position, and overpayment. Combined with the plan-tier caveat and unit flexibility, an agent has everything needed to call and interpret this 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%, so the baseline is 3, but the description goes further than the schema by explaining cross-parameter semantics: unit accepts any measure and defaults to the benchmark's unit, and supplying quantity is what triggers the overpayment calculation. Those are behavioral linkages between parameters that 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?

The description opens with the exact question the tool answers and then enumerates the concrete outputs: difference %, FAIR/HIGH/LOW verdict, position in the benchmark's 12-month range, and overpayment. This is a specific verb+resource statement that an agent can distinguish from sibling pricing tools like estimate_packaging_price or packiq_quote_analysis.

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 framing question ('Is this supplier price fair?') makes the trigger condition obvious: you have a quoted supplier price and want it evaluated against a benchmark. However, it never names an alternative tool or states when not to use it, so sibling routing (e.g. versus packiq_quote_analysis or get_live_index) 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 declare non-read-only, non-idempotent, non-destructive, but add no auth or quota detail. The description supplies the two traits an agent most needs before calling: account requirement and the 1 Suite run spend. It stays silent on whether the project itself is mutated or merely analyzed.

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

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

A single dense sentence front-loads the purpose, then appends mode, auth, and cost clauses. Nothing is redundant, though the sentence is long enough that the cost/auth guardrails could be easier to scan.

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

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

Covers purpose, prerequisites, and cost for a 5-parameter tool with a nested object and no output schema. It omits any indication of what is returned or whether the underlying project state changes, which matters given the non-read-only annotation.

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 80% and the description adds the project-vs-material duality that explains why project_id and index_category are alternatives. Beyond that it adds no format or semantic detail for goal, performance, or material; 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+resource ('Optimise a Design Studio project (or a material)') and enumerates the option classes produced (right-size, lightweight, substitute) with cost/carbon savings. It is distinguishable from siblings like draft_packaging_spec and cost_packaging_spec, though the name's 'compare' framing never appears in the description.

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

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

Gives clear operating context: it works either on a project or a bare material, requires an OPN account (sign-in or API key), and costs 1 Suite run. It does not name alternatives or state when-not-to-use, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context the annotations lack: an entitlement gate ('Professional plan and above') and the fact that values are normalized to USD with spreads measured against a reference region. It omits rate limits or result-size behavior, hence 4 rather than 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?

A single dense sentence with the core operation front-loaded and no filler; the em-dash example ('PP in Europe, US, China and the Middle East') earns its place by making the scope concrete. Slightly compressed punctuation makes it marginally less scannable than ideal.

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 burden and does communicate the shape of the result (USD prices plus spreads vs a reference). For a 5-parameter, zero-required read-only tool it covers purpose, key parameters and the plan gate adequately, though it never mentions the 10-code cap or the default European reference that the schema hints at.

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 still adds meaning beyond the schema by tying freight_per_unit and duty_pct together into a 'landed costs' outcome and clarifying that spreads are relative to the reference region, which explains why reference and duty_pct 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 names a specific verb and resource — comparing one material's price across named regions in USD with spreads against a reference region — and extends it to landed-cost comparison. An agent can distinguish it from price-listing siblings like get_prices or get_live_index. It stops short of explicitly naming which sibling to use instead, which keeps it at 4.

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 implies when the extra parameters matter ('add freight per unit and duty % to compare landed costs') and states a plan prerequisite ('Professional plan and above'), but never says when to choose this tool over alternatives such as get_prices or packindex_query. Usage 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 only mark it as non-read-only, non-idempotent, non-destructive. The description adds real behavioral context beyond that: it requires the user's OPN account (sign-in or API key) and consumes 1 Suite run, and it reads live PackIndex values rather than cached data. It stops short of saying whether the run is spent on failure or what happens if neither input is supplied.

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 core action and its scope lead, followed by the operational prerequisites. Nothing is repeated from the title or annotations.

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

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

For a non-idempotent, run-consuming tool with no output schema, the description covers what it produces (a BOM anchored to live indices), the auth requirement, and the cost. It is nearly complete, missing only edge-case behavior such as error handling or whether both optional inputs can be passed together.

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 the spec-object alternative to project_id but adds no format, precedence, or mutual-exclusivity detail beyond what the schema already provides for these two params.

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: 'Derive the bill of materials for a Design Studio project (or a spec object)' and clarifies it anchors components to live PackIndex values. This is meaningfully distinct from siblings like draft_packaging_spec or estimate_packaging_price, though it never names those alternatives to sharpen the boundary.

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 schema note 'From draft_packaging_spec' suggests drafting precedes costing, but the description itself gives no explicit when-to-use or when-not-to-use guidance versus the pricing/estimation siblings. It does surface the precondition (OPN account) and cost (1 Suite run), which is useful context.

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 only cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds concrete behavioral facts beyond them: an authentication requirement, a metered cost (1 Suite run, with Intelligence including free runs), and that the result persists as a Design Studio project rather than being returned ephemerally.

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 waste: the purpose and output shape come first, followed by the cost/auth prerequisites. Nothing is repeated from annotations and nothing extraneous is included.

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 does the work of explaining the returned artifact (a stored spec covering format, materials, dimensions, quantity, assumptions). Purpose, auth and cost are all covered; the only real gap is parameter-level detail, which is scored separately.

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 0%, so the description must carry parameter meaning, but it only loosely maps 'plain-language packaging brief' to the required 'brief' argument and never mentions 'project_name' nor the length ceilings. Two undocumented parameters leave the schema as the sole source of truth.

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 ('Turn a plain-language packaging brief into a structured spec') and enumerates the resulting content (format, materials, dimensions, quantity, assumptions). No sibling tool performs this transformation, so its scope is unambiguous against the pricing/index/quote tools it sits beside.

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 usage context plus prerequisites absent from siblings: it needs a signed-in OPN account or API key and consumes 1 Suite run. It stops short of naming the close cousin cost_packaging_spec or stating when to prefer this over it, so the routing guidance is implicit rather than 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?

With readOnly/idempotent/destructive annotations already covering the safety profile, the description still adds meaningful behavior: it anchors to the PackIndex RSC benchmark, returns a low/mid/high band, an optional order total, a next-quarter projection, and 'the sources to cite'. These are return-behavior details the annotations don't provide.

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

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

A single dense sentence that front-loads the core action (price a box) and packs the scope and return shape efficiently. Every clause carries information; only mild density cost given no line breaks.

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, so the description must convey the return shape, and it does (low/mid/high band, optional order total, projection, cited sources). The main gap is unstated region/currency semantics, which are only partly recoverable from 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 low at 22%, so the description does real work: it enumerates flute values (E, B, C, F, double-wall), states dimensions are internal, maps 'order total' to quantity, and 'next-quarter projection' to horizon. It leaves region and currency unexplained, so it compensates well but not fully.

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

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

Specific verb+resource: it prices a corrugated RSC box (FEFCO 0201) from dimensions and flute, anchored to the PackIndex RSC benchmark. It names the distinguishing scope details (RSC/FEFCO 0201, internal dimensions, low/mid/high band) that separate it from generic siblings like get_prices or cost_packaging_spec.

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 when it applies (you have internal box dimensions and a flute type and want a benchmarked estimate), but it never states when-not to use it or names an alternative such as cost_packaging_spec, get_prices, or compare_regions. Usage is only inferable from the narrow scope.

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 covered. The description adds genuinely new behavioral context: the decomposition logic (inputs + residual margins/demand/supply) and the plan-tier requirement, which annotations cannot express. It stops short of describing the response shape or latency.

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

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

Front-loaded with the motivating question, then a single dense sentence covering periods, decomposition mechanics, and examples. Every clause earns its place, though the inline examples make it slightly heavy for a two-parameter tool.

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, closed-world explanation tool with no output schema, the description conveys what the answer conceptually contains (attribution across inputs plus residual) and the access tier. 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 50%: 'code' is documented with examples and a search_indices cross-reference, but 'period' has an enum and default with no schema description. The description recovers part of that gap by enumerating the periods (1w/1m/3m/6m/1y), but adds no meaning to 'code' beyond the schema. Baseline 3 for partial coverage.

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

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

The description states a specific verb+resource ('Explain a price move') and then defines exactly what the explanation is: a decomposition of the change into input moves and residual factors, with concrete examples (PP ← propylene, gas, power). This is distinctive enough to separate it from data-fetching siblings like get_index_history or get_index_forecast, though it never names an alternative explicitly.

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

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

Usage is implied by the framing question 'Why did a price move?' and the plan gate ('Essential plan and above'), which tells the agent who can call it. However, there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as get_index_history or get_market_movers for related questions.

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 behavior, so safety is covered. The description adds real context beyond that: results carry a price-vs-PackIndex benchmark comparison, and the auth requirement differs by parameter (project_id needs the user's OPN account, material code does not). Return format and result caps are not described.

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, all informative and front-loaded with the core capability before the usage trigger and the auth nuance. Dense but no filler; the benchmark and country-filtering clauses both earn their 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 a zero-required-parameter read-only search with no output schema, the description is sufficient: it explains what is searched, what comes back, and the auth split. It does not cover result limits or pagination, a minor gap for a listing search.

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 tying project_id to an OPN-account requirement and noting that a material code works for anyone, which is access semantics not present in the parameter descriptions.

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: finding suppliers who can quote a material or Design Studio project. It further specifies the two result classes (live Trade Exchange listings with PackIndex price comparison, plus matched converters from the verified network), which separates it from search_exchange_listings and the index/price siblings.

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

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

"Use before post_rfq" gives an explicit trigger context, and the OPN-account note clarifies the precondition for project-based lookup. It does not explicitly name an alternative to use instead, which keeps it 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value: the L0-L3 layer semantics (including that L2/L3 are paid-plan-gated) and the fact that next_offset appears while more rows remain. It does not describe row contents, which is a minor gap given 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. The purpose and layer scoping come first, the alternative routing second, the pagination mechanic last. Zero filler.

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

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

For a read-only, no-required-param list tool with no output schema, the description covers what matters: what is returned per layer, the routing to get_prices, and the pagination contract including next_offset. Only the shape of an individual row is unstated.

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

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

Schema coverage is 0%, so the description carries the burden, and it mostly does: the opaque L0-L3 enum codes are explained by domain meaning, and limit/offset are tied to pagination with next_offset. What is missing is any hint of sensible limit values or offset step behavior, but the core semantics are supplied.

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 (page/list) and resource (index values), plus the scoping dimension (layer L0-L3). It names a sibling it is not (get_prices), so an agent can distinguish it from the price-lookup tools 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?

Explicitly routes usage: 'Prefer get_prices for specific codes; use this for portfolio scans.' That gives both the when-not and the when, and the pagination sentence explains how to iterate. Nothing critical 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, and non-destructive behavior, so the safety profile is covered. The description adds substantive domain context beyond that: the unit conventions by material class, the A-D gradation, and virgin vs PEF CFF variants, which help the agent anticipate the shape of the 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?

Front-loaded with 'Carbon footprint' and kept to one dense sentence plus a short application note; nothing is padded. It leans heavily on domain jargon (L3, CFF, cullet) but the length is appropriate.

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 return values and largely does — units, grades, and material classes are spelled out, and annotations cover the safety profile for a 2-parameter lookup. The main gap is the absence of routing guidance against the other index tools.

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

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

Schema coverage is 100%, so both parameters are already documented. The description echoes the recycled-content optionality and adds the surrounding context (virgin and PEF CFF), but no syntax or format detail beyond what the schema provides — the baseline of 3 applies.

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

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

The description specifies the resource precisely (carbon footprint factors for finished packs and raw materials) and the conventions used (kg CO2e per unit vs per tonne, grade A-D). It never states the retrieval verb explicitly, but the domain content is specific enough to distinguish it from the price/forecast siblings.

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

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

'For Scope 3 Category 1: factor × units or tonnes' gives context for how the returned value is applied, which is useful. However, it never says when to pick this tool over get_live_index, get_index_history, or get_all_indices, so tool selection 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 this as a read-only, idempotent, non-destructive lookup. The description adds useful behavioral detail by specifying the 12-week horizon and the returned content: current level, projection, projected change, and confidence. It does not clarify confidence semantics or any plan limitations.

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

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

The description is compact and front-loads the forecast horizon and output content. The fragment “Intelligence plan.” is terse and somewhat unclear, but overall the structure is efficient.

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

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

For a simple read-only forecast lookup with a fully described two-parameter schema and no output schema, the description adequately covers the forecast window and returned fields. Minor gaps remain around what “Intelligence plan” means and how confidence is expressed.

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

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

Schema description coverage is 100%, so both parameters are already documented, including PackIndex examples and the currency conversion behavior. The description adds only the broad categories of PackIndex codes, not parameter syntax or additional meaning beyond the schema.

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

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

The description states a specific resource and scope: a 12-week forward value for any PackIndex code, including current level, projection, projected change, and confidence. The 12-week forward framing distinguishes it from sibling tools like get_live_index and get_index_history.

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 forecast purpose is clear enough to imply when to use it, but the description does not explicitly name alternatives such as get_live_index or get_index_history or state when not to use this tool. The trailing “Intelligence plan” note hints at an access context without explaining 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context: sampling granularity (every point ≤3mo, weekly closes beyond), plan-dependent depth caps, and the free-tier cutoff. That is meaningful disclosure beyond 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?

Front-loaded with the core purpose and packs resolution rules, depth limits, and free-tier cutoff into a compact two-clause structure. Dense but each clause carries information; slightly crammed with semicolons rather than wasteful.

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 describes the return shape (one value per date plus the change between points) and the sampling behavior. Only minor gaps remain, such as response format and pagination for longer spans.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra by spelling out the plan-to-depth mapping (observer/essential 3mo, professional/intelligence 24mo) that the schema only alludes to as 'Capped to the caller's plan depth'.

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 ('Price history for any PackIndex code') and adds resolution/scope detail (one value per date, L0-L3 coverage). It clearly implies historical data versus live/forecast siblings but never names an alternative, so it stops short of full sibling differentiation.

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 through the plan-depth note and 'free history ends 12 weeks ago', which tell the caller about limits but not when to pick this over get_live_index or get_index_forecast. No explicit when-to-use or when-not-to-use guidance is 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?

With annotations covering the safety profile, the description adds substantial behavioral context beyond them: the free-tier 12-week delayed value with a daily live rotation, the Essential-plan requirement for live data, that change periods appear only where sufficient history exists, and that carbon data appears only where scored. These are real constraints an agent must know.

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, but it is front-loaded with the core purpose and each parenthetical (index levels, period availability, tier gating) earns its place. Slightly heavy on nested parentheses, though justified by the amount of genuinely useful 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 carries the return-value burden and does so fully: value in USD and user currency, four change periods with their history caveat, and carbon data. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100%, so both parameters (code, currency) are fully documented in the schema, including the search_indices fallback and FX conversion. The description restates currency conversion ('in USD (and your currency)') but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (today's value of one PackIndex code) and scopes it precisely to the L0–L3 index hierarchy. 'One' and 'Today's value' clearly separate it from get_all_indices and get_index_history.

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 establishes clear context — single live index value today — which implicitly routes the agent away from history, forecast, and bulk-list siblings. It stops short of naming alternatives or stating when-not to use it (e.g., 'for historical series use get_index_history').

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 and idempotentHint, so safety is covered. The description adds the plan gating ('Essential plan and above') which is genuinely useful behavioral context, but says nothing about result ordering, limits, or response shape.

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

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

One dense sentence front-loads the core function then tacks on period and group modifiers. No wasted words, though the parenthetical layer definitions and group examples make it slightly cramped.

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 ranking tool with no output schema, the description covers scope, layers, periods, and plan gating. It omits tie-breaking/ordering, the meaning of limit per direction, and default period behavior, so an agent still infers call shape from the schema.

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

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

Schema coverage is only 25%, but the description carries the meaning of layer, period, and group ('optionally within a group (e.g. polymer, fibre, energy)'). It does not explain period semantics as windows for the ranking or what limit counts, leaving some gaps unbounded by either schema or description.

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

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

States a specific verb+resource ('Biggest risers and fallers among inputs (L0), raw materials (L1) and semi-finished (L2)') with the material layers it covers, distinguishing it from generic price tools like get_prices or get_live_index.

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 or naming of alternatives. It mentions 'Essential plan and above' as an access restriction, but does not route an agent to get_prices, explain_price_move, or get_index_history for adjacent needs.

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 substantive behavioral context the annotations cannot: what the response contains (bid counts, and supplier contact details that only appear after a supplier replies).

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 core purpose front-loaded and the parameter behavior trailing after the semicolon. Efficient, though the nested parenthetical makes it slightly hard to parse on first read.

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 describe return content, and it does (counts of recipients and responses, bids, contact info). The single optional param is also covered. A note on what an empty response or missing rfq_id looks like would close the remaining 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 coverage is 0% and the single parameter has no inline description, so the description carries the full burden. It does so adequately, explaining that rfq_id switches the call to per-RFQ response retrieval. It stops short of stating the accepted id format or that omission lists everything, but the intent is clear.

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

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

States a specific resource ('the user's sent RFQs') plus the aggregate payload (supplier recipient count and response count), which clearly separates it from write-oriented siblings like post_rfq. It does not, however, name or contrast against any 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?

Explains the two invocation modes: call it plain to list RFQs with counts, or pass rfq_id to drill into responses. That is real conditional guidance, though no alternative tool is named for adjacent needs.

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 description's real contribution is "Free callers get 12-week delayed reference values" – a data-freshness caveat tied to account tier that no annotation conveys. It also discloses the returned change windows, though it says nothing about response shape beyond that.

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

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

Two sentences, zero padding, and the core capability plus the 20-code scope are front-loaded ahead of the free-tier caveat. Every clause carries information.

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

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

With no output schema, the description usefully conveys what comes back (values plus multi-horizon changes) and the tier-based delay. It stops short of explaining currency behavior or error cases for invalid codes, but is sufficient 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 description coverage is 100%, with codes documented and exemplified and the maxItems/minItems bounds present, so the baseline is 3. The description adds the useful enumeration of index layers (oil, gas, resins, pulp, board, films, finished packs), which broadens understanding of valid codes but does not document the currency parameter's behavior.

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 with concrete scope: today's values for up to 20 PackIndex codes in one call, across any index layer, with 1w/1m/3m/1y change windows. This clearly separates it from siblings like get_index_history (historical) and single-index lookups such as get_live_index.

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?

"For watchlists and cost models" implies the intended use case but names no alternatives and gives no when-not condition. An agent can infer batch retrieval should be used over single-index calls, but this is left to inference rather than stated.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds non-annotation context: an auth/account requirement and the fact that quota-style 'Suite runs left' is returned alongside project metadata. It stops short of noting result size or ordering, but for a zero-argument personal list that is minor.

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: resource and return shape first, usage/routing second, prerequisite last. Every clause earns its place and the routing guidance is front-loaded where an agent will read 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 parameters, no output schema, and full annotation coverage, the description covers what the agent needs: what it returns, when to call it, and the account requirement. The phrase 'Suite runs left' is slightly cryptic and its units/meaning are never explained, which is the only real 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?

The tool takes zero parameters, which sets the baseline at 4. The description instead characterizes the response contents (id, name, pack type, status, Suite runs left), which is useful orientation even though it does not substitute for parameter documentation that does not exist.

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 ('The user's Design Studio packaging projects') and enumerates the returned shape (id, name, pack type, status, Suite runs left). It also names the sibling tools it precedes (compare_packaging_options, post_rfq), so an agent can distinguish it from the rest of the list 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?

Explicit triggering condition: use it 'when the user refers to "my project" without an id,' and it names the downstream tools that depend on its output. It also states the account prerequisite ('Requires the user's OPN account'), leaving nothing 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, and destructiveHint=false, so the safety profile is covered. The description adds that the answer is 'structured' and 'citable' and grounded in PackIndex data, which is useful return context given there is no output schema, but it does not disclose format, sources, or limits.

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

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

Two compact clauses with the action front-loaded and no wasted words. Every phrase carries information.

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

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

For a simple two-parameter query tool with no output schema, the description covers the action and gives a brief return hint, but it omits routing guidance against 26 siblings and any detail on how the answer is produced or bounded.

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 50% (currency documented, question limited only by maxLength), and the description never mentions the parameters at all. It does not compensate for the undocumented 'question' constraint or clarify currency behavior 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?

The description states a clear verb ('Ask a plain-English question') and the resource domain (packaging costs, indices, or which PACKIQ agent to use), so an agent knows this is a natural-language entry point. It stops short of explicitly distinguishing itself from data-specific siblings like get_prices or get_all_indices, though the routing hint implies its role.

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 naming the kinds of questions it accepts (costs, indices, agent selection), but there is no explicit when-to-use/when-not guidance and no alternative tool is named. With ~26 siblings, a routing statement would have been valuable.

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 idempotentHint=false but don't explain why; the description supplies the missing rationale by disclosing the OPN account requirement, a 4-credit cost, and automatic refund on failure. That is real behavioral value beyond the structured fields, though it says nothing about run duration, rate limits, or partial-failure fee handling.

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, and the output summary is front-loaded before the account/credit caveats. Every clause carries information an agent needs.

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

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

There is no output schema, but the description enumerates the three return artifacts (fee band per format, total liability by market, reformulation priority list), and covers auth, cost, and refund behavior. Nothing essential for a correct call 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?

Single parameter with 100% schema description coverage, so the baseline is 3. The description echoes the schema's framing ("packaging portfolio as text: formats, materials, unit weights, annual volumes and markets") without adding format or syntax guidance such as an example payload.

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

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

Specific verb ("Estimate") plus resource ("annual Extended Producer Responsibility fees") plus scoped domain (packaging portfolio across named schemes). No sibling in the list computes EPR fees, so it is trivially distinguished from check_quote, cost_packaging_spec, and packiq_recyclability.

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 when the tool applies (you have a packaging portfolio and want scheme-level fee liability), but it names no alternative and gives no exclusions — e.g. it doesn't say when to reach for packiq_quote_analysis or cost_packaging_spec instead. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds key operational context the annotations cannot: it requires an OPN account, consumes 2 PACKIQ credits, and auto-refunds on failure. It also discloses the >8% threshold that triggers market evidence, exceeding baseline behavioral detail.

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 tightly packed sentences with zero filler; the core function is front-loaded and the cost/auth caveats are appended rather than buried. Every clause earns its place.

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

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

With no output schema, the description still tells the agent what comes back (per-line deviation plus verdicts and evidence) and covers the two hidden costs of invocation – account requirement and credit spend with refund policy. Complete for a single-parameter tool of this 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?

Schema description coverage is 100% and the single 'input' parameter is already fully documented as text with items, specs, quantities, prices and currency. The description restates 'pasted supplier quote' but adds no format or syntax beyond what the schema provides, 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 (benchmark) and resource (every line of a supplier packaging quote) and even enumerates the verdict taxonomy (Sharp, Competitive, High, Overpriced). It is far more specific than a tautology, but never names or contrasts a sibling like check_quote or estimate_packaging_price, so an agent must infer the distinction.

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 tool takes a 'pasted supplier quote' and returns a line-by-line benchmark, so the agent can guess the scenario. There is no explicit when-to-use, when-not-to-use, or named alternative despite several plausible siblings (check_quote, estimate_packaging_price).

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 non-read-only, non-idempotent, non-destructive, closed-world, which matches a paid run-and-return operation. The description goes beyond them with the credit cost, the automatic refund on failure, and the OPN account requirement — the key behavioural facts an agent needs before invoking a metered tool.

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

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

Two sentences, front-loaded with the core action and scale, then the operational constraints. Dense but essentially every clause carries information; no padding or repetition.

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

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

No output schema exists, so the description must carry return semantics — and it does, naming grade, reasoning, EPR eco-modulation impact and options to reach a higher grade. Combined with cost and auth disclosure, an agent has everything needed to call this 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?

Only one parameter and schema description coverage is 100%, so the schema already documents the 'input' string fully. The description's enumeration of substrate, layers, inks, closures and adhesives largely restates what the schema describes, adding little beyond it.

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 ('Grade a packaging structure') plus the exact framework and output scale (EU PPWR recyclability, A to F) and the inputs considered. An agent can distinguish this from siblings like packiq_epr_fees or packiq_quote_analysis without opening any schema.

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

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

Gives clear preconditions: requires the user's OPN account and costs 4 PACKIQ credits, refunded automatically on failure. It doesn't explicitly say when to prefer this over neighbouring tools such as packiq_epr_fees, but the cost/auth context is unusually concrete.

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

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

Goes well beyond the annotations by disclosing the real-world side effect ('Real e-mails are sent'), the anonymity behavior (the Exchange contacts suppliers for the buyer), and hard prerequisites (verified e-mail, Business+ plan). The instruction to confirm selection with the user first is exactly the kind of operational guidance annotations cannot 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?

Front-loads the core action and resource in the first sentence, and each clause carries information (prerequisites, defaults, anonymity, the e-mail warning). The middle em-dash clause is dense and slightly run-on, but there is no filler.

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

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

For a 12-parameter, zero-required mutation tool with side effects and no output schema, the description covers the critical prerequisites, the two targeting paths, and the confirmation warning. It is thin on the quantity/unit/currency/target_price and broadcast parameters, which an agent filling the form would still have to 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 coverage is 58% across 12 parameters; the description adds real meaning for listing_ids and company_slugs (their source and the anonymous-contact behavior) and implies material_id/project_id usage, but quantity, unit, currency, target_price, needed_by, notes, region and especially broadcast get no mention. Note also that the description sources listing_ids from find_suppliers while the schema says search_exchange_listings.

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 ('Request quotes on the OPN Trade Exchange') plus scope (a Design Studio project or a PackIndex material code, up to 3 suppliers). This clearly separates it from siblings like get_my_rfqs (read) and find_suppliers (discovery), so an agent can pick it 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?

Explains the two targeting modes (listing_ids, or best-matching listings by default; company_slugs to ask specific converters) and names prerequisites (verified e-mail, Exchange plan with RFQs / Business+). It points to find_suppliers as the source of IDs, but does not say when to choose material_id/project_id over listing_ids/company_slugs, so it stops short of full when/when-not coverage.

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 genuinely new context: it enumerates the return payload (adjusted price, per-index ratio and effect, formula) and discloses a base-date lookback limit that is not in the annotations. The 'rest is fixed' convention is a useful behavioral detail, though rate limits or failure modes are not covered.

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 operation, then inputs, then outputs, then constraints. No filler; every clause carries information.

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

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

For a read-only calculator with no output schema, the description supplies the return shape and a key access constraint, which is most of what an agent needs. It stops short of clarifying the shortcut-vs-components input choice, the only remaining 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 coverage is 71%, so most parameters are documented structurally. The description reinforces base price/date and the weights concept and adds the 'rest is fixed' meaning, but it never disambiguates the top-level code/weight shortcut from the components array, which is the one genuinely ambiguous part of the schema.

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

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

States a specific verb and resource ('Recalculate an index-linked contract price') and clarifies the inputs (base price, base date, indices, weights) and the fixed remainder. This distinguishes it from calculation-adjacent siblings like estimate_packaging_price and explain_price_move, though it does not name any 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?

The plan-tier note ('Essential plan (base dates up to 3 months back), Professional (24 months)') gives a real precondition, but there is no explicit statement of when to choose this over explain_price_move or get_index_history. Usage 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 cover read-only/open-world/idempotent/non-destructive, and the description adds genuinely new behavior: benchmark data is live on paid plans and 12-week delayed otherwise, and listings deliberately omit contact details. The tiering caveat materially affects how an agent should interpret the returned benchmark values.

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 with no filler; the resource and filterability lead, and the data-freshness caveat and contact caveat follow. Efficiently front-loaded, though the parenthetical tiering clause takes some unpacking.

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 does the work of telling the agent what a listing contains (supplier offer plus a PackIndex benchmark) and what it does not (contact details). Pagination/limit behavior is left entirely to the schema, which is a minor gap for a 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 75%, near the high-coverage baseline, so the schema already documents query, region, and material_id. The description reinforces the PackIndex material-code and origin filters but says nothing about the query keyword field or the limit cap/default, adding little beyond the schema.

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

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

States a specific resource (live supplier offers on the OPN Trade Exchange) with a clear action (search) and names the filter dimensions. It implicitly separates itself from contact-oriented siblings by noting 'No contact details — RFQs happen on the Exchange,' but never names the nearest alternative (find_suppliers) 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 context is implied: this is where you browse live supplier offers, and the closing clause points the agent toward the Exchange RFQ flow for contact. There is no explicit when-to-use-vs-alternative statement against find_suppliers, get_prices, or post_rfq.

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 description's job is to add return behavior — and it does, stating the result carries layer, region and unit but 'no prices'. That negative disclosure is genuinely useful for an agent deciding where to get pricing data. Rate limits, result caps and ordering are not mentioned.

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 tightly packed sentences: capability first, then return shape and exclusions. Every clause earns its place — the examples, the layer legend and the 'no prices' caveat all carry information an agent needs.

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

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

With no output schema, the description usefully describes what comes back (code + layer, region, unit) and what does not (prices). Combined with annotations this is nearly sufficient; only the result-count/limit behavior is left unexplained for a search tool that caps at 25 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 coverage is only 33%, so the description must compensate. It does for 'query' by giving literal example search terms and for 'layer' by translating L0–L3 into plain language, though layer semantics are already in the schema. The 'limit' parameter (default 10, max 25) is never addressed, leaving a gap the description should have closed.

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 ('Find PackIndex codes') and enumerates the searchable dimensions (material, input, format, plain words) with concrete example queries. An agent can tell this apart from lookup-style siblings like packindex_query 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?

'Use first when you don't know the exact code' gives a clear selection condition and implicitly positions this ahead of exact-code lookup tools. It stops short of naming the alternative tool to use once the code is known, so the routing is only half 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 readOnlyHint=false, destructiveHint=true, idempotentHint=true, but the description adds real context the annotations cannot: the update is free with no Suite run, and a new quantity re-prices the existing bill of materials. It also explains the right-sizing and performance-floor conditions (floor applied only when both current and required are supplied). It does not spell out what 'destructive' means here, so not a 5.

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

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

Two sentences, front-loaded with the updatable fields before the cost/behavior notes. Dense but each clause carries information; the long parenthetical unit list makes it slightly harder to scan.

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?

A 6-parameter nested-object mutation tool with no output schema, and the description covers purpose, cost, side effects on the BOM, and the performance-floor pair rule. Only gap is the absence of any statement about what the call returns or confirmation behavior.

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 67%, and the description largely mirrors the schema's own wording (region as target market, contents_mm as box dimensions, ECT/stiffness/top-load per material). It does add the domain framing of 'contents size (boxes)' enabling right-sizing, but adds little syntax or semantics beyond what the schema already documents.

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

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

States a specific verb (change) and resource (a Design Studio project) and enumerates exactly which fields are updatable: quantity, region, contents size, name, performance floor. It also disambiguates from read-only siblings like list_my_projects by framing this as the mutation path.

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 a concrete activation condition: 'Use it when the user gives the real volume before comparing options or requesting quotes,' which implicitly routes to compare_packaging_options/check_quote. It does not state when NOT to use it or name the alternatives explicitly, 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.