catalogue

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: it signals a 'Pro' access tier, states 'Reads only', and describes nuanced report contents such as superseded rows and SKUs missing default-currency pricing. No contradiction with annotations.

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

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

The description is one efficient sentence followed by two short useful fragments ('Reads only.' and 'Pro.'). The core action is front-loaded, every clause adds information about the report's scope or contents, and there is 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 required parameters, two well-documented optional parameters, and read-only annotations, the description covers everything an agent needs to invoke the tool correctly. The output schema is absent, but the description compensates by enumerating the report sections that will be returned.

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%: date is documented with YYYY-MM-DD format and a today default, and limit is documented with per-section row bounds and a 500 ceiling. The description adds little beyond the phrase 'as at date', so it does not need to compensate for missing schema detail.

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 begins with a specific verb and resource ('Report the catalogue as at date') and then enumerates exact output categories: SKU counts, in-force price rows, superseded rows, and SKUs missing a default-currency price. This clearly distinguishes it from sibling list/retrieval tools like sku_list and price_list_text, which return raw records rather than aggregated report sections.

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 provides no explicit guidance on when to use this tool versus alternatives, nor any when-not conditions. It only implies report-style usage via 'as at date' and 'Reads only', but does not name sibling tools or explain that sku_list/price_list_text should be used for raw or formatted listings.

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 indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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 two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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 single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent 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?

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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

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

The description uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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 provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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 cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke 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?

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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 explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state 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 readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds concrete behavioral details beyond annotations: it transforms lines into invoice/quote-ready items, prices from catalogue, refuses unknown codes by name without pricing them, and states the operation is free. These are useful runtime behaviors not encoded in 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 the main action, and every sentence adds value. It says what the tool transforms, what it produces, the pricing basis, unknown-code refusal, and cost.

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

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

Given the rich input schema (100% parameter coverage) and the annotations (readOnly, idempotent, non-destructive), the description is complete enough: it explains the purpose, the refusal behavior, and cost. No output schema is needed because the tool feeds well-known invoice_create/quote_create flows.

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 each parameter fully. The description's added value is the overall orchestration (making lines invoice/quote-ready from catalogue pricing) rather than per-parameter semantics, 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 transformation verb ('Turn a list of sku or role lines into invoice_create-ready and quote_create-ready items priced... from the catalogue as of each line's date') and clearly differentiates from siblings like sku_list, rate_get, and price_list_pdf. It also highlights a key behavioral guarantee (unknown code is refused by name and never priced).

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 specifies what to use the tool for (build invoice/quote lines) and provides context like 'as of each line's date' and 'free', but doesn't explicitly name alternatives to avoid or state when not to use it. The sibling list is broad, so an explicit 'when not to use' would have been stronger.

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 read-only/idempotent/non-destructive profile. The description adds genuinely useful behavior: the endpoint has no PDF renderer, the download link expires after one hour, and the list contents (SKU, unit, in-force price, effective date). No contradictions.

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 instruction is front-loaded in a single sentence, and the caveat about the missing PDF renderer is included without bloat. The stray 'Pro.' is slightly confusing, but it does not materially hurt clarity.

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 tool with four optional parameters and no output schema, it covers the rendered format, the one-hour expiry of the result link, and the contents of the price list. It is sufficient for an agent to invoke the tool and know what to expect back, though it leaves the exact meaning of 'Pro.' 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 100%, so the parameters are already well documented; the description reinforces the currency/tier/date scoping but mostly repeats what the schema says. It adds value mainly at the document level (A4, print layout), not in explaining individual 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?

It names an explicit action ('render'), an exact resource ('the price list for one currency and tier'), and the output form ('A4 HTML document laid out for print-to-PDF'). This differentiates it from the sibling price_list_text by the medium and rendering goal.

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 opening 'Call this tool to render...' sets a clear context: use it when you need an A4 HTML/print-to-PDF price list. It does not explicitly name price_list_text as the alternative or state when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: the output includes both current and later-booked prices, the business name is used, and a .txt download link is returned that is valid for one hour.

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 carry the main purpose, the output details, the download-link behavior, the pricing note, and the sibling alternative. Every clause earns its place, and the core action is front-loaded.

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

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

Despite having no output schema, the description tells an agent what will be returned: plain text with SKUs, units, prices, labour rate cards, business name, and a one-hour-valid .txt link. Together with the rich annotations and fully documented parameters, nothing essential is missing for a correct call.

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 fully documents the three parameters and their defaults. The description references a 'date' in the output phrase 'price in force on a date,' but it does not add meaning beyond what the schema already provides for 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?

The description opens with a specific verb and resource: 'Print the price list as plain text' and then specifies exactly what is included (every SKU with unit, price in force, later booked prices, labour rate cards, business name). It also distinguishes itself from the sibling price_list_pdf by noting that the PDF variant 'writes the A4 page.'

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 names the sibling price_list_pdf and contrasts it with the plain-text output, so an agent can infer which format each tool produces. It does not explicitly state 'use this when you need plain text and not a PDF,' but the contrast is clear enough to be useful.

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, and the description adds valuable context beyond them: the exact temporal selection rule ('the row picked is the latest valid_from at or before that date'), the no-role behavior, and the cost ('Free'). There is no contradiction with 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?

The description is two short sentences that front-load the core purpose ('Show the hourly rate...') and append only necessary selection and edge-case details. 'Free.' earns its place by flagging cost without adding noise.

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 lookup with zero required parameters, the description covers purpose, selection logic, the optional-role branch, and cost; remaining defaults are already present in the schema. The safety profile is carried by annotations, so nothing needed to invoke 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 coverage is 100%, so the schema already documents each parameter's format and defaults. The description adds meaning by tying date to the valid_from snapshot lookup and by clarifying that omitting role triggers a full-card listing, which goes beyond the baseline.

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

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

The opening clause uses a specific verb ('Show') with a clear resource ('hourly rate') and qualifiers (role, date, currency), so an agent knows exactly what the tool returns. It also distinguishes itself from siblings like rate_set by describing a read-only lookup and the no-role mode that lists every card.

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 a clear conditional usage: when no role is given, it lists every card; with a role, it returns the rate for that role as of a date. It does not explicitly name rate_set as the write/update alternative, so the when-not 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?

Annotations provide no behavioral hints (all false), so the description carries the burden. It discloses the key behavior: the same role/currency/date replaces that row rather than adding one, which is critical for an agent to understand persistence semantics. It also notes 'Free,' which may imply no cost. This is substantive transparency beyond the schema.

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

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

Two sentences, front-loaded with the core action and fields. Every clause earns its place: the replacement rule and the 'Free' note are both relevant. No fluff 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?

For a mutation tool with 6 parameters, 83% schema coverage, and no output schema, the description covers the essential behavioral semantics (replacement, field units, default currency implicitly). It doesn't mention edge cases like validation or side effects, but those are minor for a setter. The sibling list reinforces its role. Adequate 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 description coverage is 83%, so the schema already documents most parameters. The description reinforces hourly_minor as whole minor units and alludes to the start day, but adds little beyond what the schema provides. It does not introduce new semantic insight beyond the schema's own 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?

The description states a clear verb ('Set'), a specific resource ('hourly charge-out rate on a labour card'), and enumerates the key fields (role, currency, hourly_minor, start day). It also clarifies the replacement semantics, distinguishing it from a simple add. This differentiates it from siblings like rate_get and sku_set without ambiguity.

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 makes the tool's purpose obvious (setting a rate) and implies it is the counterpart to rate_get for retrieval. It does not explicitly state exclusions or when to prefer an alternative, but the context is clear enough for an agent to select it appropriately. No misleading 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?

Beyond the destructiveHint=true annotation, the description adds valuable behavior: deletion frees a free-tier slot, and the tool refuses when dependencies exist, naming them. This explains not just the destructive nature but the conditional and failure behavior, which the annotation alone does not 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?

The description is a single dense sentence that front-loads the core action and conditions, then gives the refusal behavior and fallback. There is no filler and every clause contributes useful decision-making 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 single-parameter destructive tool with strong annotations and a rich description, the definition is complete enough. It covers preconditions, success effect, refusal behavior, and the alternative path, so an agent can decide when and how 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% and the parameter description already explains the SKU code format and the product-name fallback. The tool description adds contextual framing about catalogue lines and dependencies, but it does not add meaning specifically about the 'sku' parameter beyond what the schema already provides.

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

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

The description uses a specific verb ('delete') with a specific resource ('catalogue line') and states the exact preconditions under which deletion succeeds. It also distinguishes itself from sibling tools like sku_set and sku_get by framing this as a removal operation with dependency constraints.

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 explicitly states when the tool is usable: only when no rate card points at the SKU and it never priced a resolved line. It also explains the refusal behavior and names the alternative action ('reprice it to withdraw it instead'), giving the agent clear 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 and idempotentHint, so the safety profile is covered. The description adds useful non-obvious behavior: the valid_from selection rule ('latest valid_from at or before that date') and the output nuance about naming any later booked row. This goes beyond the annotations and 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?

The description is brief and front-loads the core purpose and selection rule in one dense sentence. 'Free.' is a small extra that adds marginal value but does not significantly clutter the description.

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

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

With no output schema, the description helpfully explains what the answer contains: the picked row and any later already-booked row. Combined with readOnly annotations and full schema parameter coverage, this is sufficient for a single-SKU read tool, though exact output format is not specified.

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 all four parameters already have clear descriptions. The tool description provides only a high-level summary ('one currency and tier') rather than per-parameter elaboration, which is acceptable given the schema carries the full 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?

The description uses a specific verb and resource: 'Show the price of one SKU as of a date, in one currency and tier.' The singular SKU/date scope clearly differentiates it from siblings like sku_list, price_list_text, and rate_get, which cover broader or different queries.

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 singular scope implies when to use it, but the description never explicitly names alternatives or states when not to use it. An agent must infer the choice between this and price_list_text or sku_list from context rather than from direct guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explicitly states that SKUs without a price in the given currency/tier are still listed (with 'none'), and that a date parameter overrides 'today'. This goes beyond annotations, though the trailing 'Free' is ambiguous and could confuse.

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 two sentences and front-loads the purpose and filters. It is concise and free of redundant phrasing. The 'Free' at the end is an odd addition that could be interpreted as a cost note or a leftover, slightly diminishing clarity, 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 list tool with 5 optional parameters and no output schema, the description adequately explains the purpose and key behavior (including no-price SKUs). However, it does not describe the response format (e.g., fields returned) or any pagination details beyond the limit parameter, which is documented in the schema. Given annotations cover safety, this is acceptable but not fully complete.

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

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

Schema description coverage is 100%, so every parameter (date, tier, limit, prefix, currency) is already documented with its meaning and defaults. The description only reiterates that filters are applied but adds no syntax or format details beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the verb 'List' and resource 'catalogue lines', with explicit filters (prefix, currency, tier) and a temporal qualifier ('price in force today'). It distinguishes itself from siblings like price_list_pdf/text by focusing on raw data output rather than formatted documents, and from sku_get by listing many lines rather than a single SKU.

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 to use it (to list catalogue lines with current prices) but does not explicitly state when not to use it or name alternatives. Siblings like price_list_text/pdf exist for formatted output, but no guidance is given to route the agent away from them. Usage context is clear but exclusions are absent.

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 carry only false hints and no real behavioral signal, so the description must carry the burden. It does disclose the key non-obvious behavior that 'a repriced line keeps its old rows' and states the 25-SKU free limit. It does not mention auth or response shape, but neither is essential for invoking a write operation.

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 with no filler: the first states purpose and key fields, the second adds the crucial versioning side effect, and the third gives the quota. Everything earns its place and the most important information is front-loaded.

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

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

For a 10-parameter tool with no output schema and weak annotations, the description covers the purpose, pricing dimensions, history behavior, and a usage limit. The schema documents the remaining parameter details. A small gap is the lack of any note about return values, but that is not required given the schema already documents fields.

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 90%, but the description adds the compound-key nuance that price_minor is set 'for one currency, tier and valid_from'. This is real meaning beyond individual schema field descriptions, clarifying how the SKU's price matrix is structured.

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 action and resource: 'Add a catalogue line or reprice one'. It also names the core inputs, making it unambiguous that this tool creates or updates SKU pricing, distinct from siblings like sku_get, sku_list, or sku_delete.

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

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

The description implies the tool is for adding or repricing catalogue lines, and the free-tier note gives a constraint, but it never explicitly says when to prefer sku_set over a sibling or when not to use it. The 'keeps its old rows' fact is behavioral, not an exclusion or alternative.

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