pops4-mcp-catalog

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

The description states the tool is 'Read-only' and lists exactly what it returns (programme cost, annual impressions, cost per thousand, multiple against bought media, and a cited Nielsen figure with its caveat). This provides full transparency into the tool's behavior, especially since no annotations are present.

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 overly verbose and repetitive, restating the same concepts (four populations, returns, usage) multiple times. It lacks a clear, concise structure and could be condensed to a few sentences without losing information.

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

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

The description provides all necessary context for an agent to decide when to use the tool and what to pass. It covers the tool's purpose, usage scenario, return values, and parameter flexibility, making it fully self-contained even with no annotations.

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 descriptions already cover each parameter well, including defaults. The tool description adds value by emphasizing that all parameters are optional and that any combination of the four populations can be supplied, reinforcing the schema's optional nature.

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 tool calculates cost per thousand for a branded programme across four populations and compares it to a buyer-supplied CPM. While the purpose is unambiguous, the description is somewhat redundant, restating the same information multiple times.

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 says when to use the tool: 'Use when a buyer asks what a culture or brand programme is worth, or how to justify the spend.' It also provides guidance on parameter usage, clarifying that any of the four populations can be supplied and that employees are optional.

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 no annotations provided, the description carries the transparency burden. It discloses key outputs: 'costed kit of real catalogue products, per-attendee cost, programme subtotal, production turnaround and quote timing,' plus shipping and blind-ship availability. It does not explicitly state side effects such as whether an order is placed or only a programme is generated, leaving some behavioral ambiguity.

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 informative but slightly verbose, with a long synonym list ('swag, merch, promo...') and shipping details that are tangential to the core generation action. The main verb and outputs are front-loaded, so it remains scannable, but it could be tightened.

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 compensates by listing the return contents: costed kit, per-attendee cost, programme subtotal, production turnaround, and quote timing. It also gives tier pricing, override behavior, shipping options, and event-phrase examples, making the tool's behavior understandable without needing to open the schema. It does not specify exact response shape, but that is not required given the output details provided.

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 covers all six parameters at 100%, but the description adds meaningful semantics beyond the schema: brand_tier price bands are expanded, and budget_per_head is explained as an override that selects the closest tier. It also clarifies that revenue_target is 'used for attribution framing only,' which is not obvious from 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?

Description opens with 'Build a complete event programme for a given attendee count and budget tier,' giving a specific verb and resource. It also clarifies that it is for event-scale requests 'rather than a single product,' which helps distinguish it from single-item tools. It does not explicitly name a sibling tool, but the purpose is still unambiguous.

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

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

The description provides direct usage guidance: 'Use when the request is an event, launch, summit or programme rather than a single product' and includes concrete example phrasings. It also instructs users to 'Supply budget_per_head to have the tier chosen automatically.' It does not explicitly say when to prefer request_program or other siblings, but the usage context is clear.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool lists all product categories, which implies a read-only, comprehensive operation. It stops short of stating permissions, potential size limits, or explicit read-only semantics, but for a zero-parameter listing tool the core behavior is clearly conveyed.

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 with no wasted words. The first sentence front-loads the primary action and result, and the second adds focused usage guidance. Every clause contributes meaning.

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?

The description is sufficient for a simple zero-parameter tool: it says what is returned, the scope ('every'), and when to use it. It lacks explicit notes on return format details or edge cases, but the output schema is absent and the described output ('item count and sample products') is enough for typical use.

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 input schema is empty with 0 parameters, giving a baseline of 4. The description adds useful context about the output shape (item count and sample products) even though no parameter explanations are needed.

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 ('List') and resource ('every product category') and specifies what is returned ('item count and sample products'). It clearly distinguishes the tool from siblings like get_product_catalog and search_products by focusing on category-level coverage rather than product-level details.

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 use it: 'to establish what the catalogue covers before searching, or to answer what kinds of items are available.' This gives clear context and ties to a search flow, though it does not explicitly name sibling alternatives or state exclusions.

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

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

No annotations are present, so the description carries the behavioral burden. It does disclose the key behavior: returns a quote, includes virtual-proof links, and reflects shipping/timing factors. It does not fully explain what virtual-proof links are or whether the operation is read-only, which keeps it from a 5.

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

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

Three sentences: purpose, when-to-use, alternative, with no filler. Critical routing information is front-loaded in the first sentence and the contrast follows immediately.

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?

The tool has no output schema or annotations, so the description must cover return value and behavior; it does state the return kind and the conditions under which it should be used. Remaining gaps are the exact response shape and meaning of virtual-proof links, but for selecting/invoking this is adequate.

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?

All five parameters are already described 100% in the schema, so the baseline is 3. The description adds semantic weight by connecting shipping_zip and event_date to shipping/timing and characterizing items as SKUs/quantities; the only slight ambiguity is 'SKUs' vs the schema's 'slug' terminology.

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?

Description uses a clear verb ('Return') with resource ('wholesale quote with virtual-proof links') and scope ('list of SKUs and quantities, optionally ... ZIP and event date'). It names sibling get_quote and distinguishes itself by shipping/timing sensitivity, so an agent can select it confidently.

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 'Use when shipping or timing affects the answer' plus direct contrast with get_quote ('plain priced list with neither'). This is textbook when-to-use and alternative guidance; no inference required.

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?

No annotations are provided, so the description bears the full burden of disclosing behavioral traits. It mentions returning data but does not explicitly state that the operation is read-only, nor does it address authentication requirements, rate limits, or error behavior. The implicit 'Return' suggests a read operation, but this is not made explicit.

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, well-structured sentence that packs the function, the input, and the output fields without fluff. It also includes the usage guidance in the same breath, making it compact yet highly informative.

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 single-parameter tool, the description provides sufficient context: it names the output fields, explains the input source, and gives a usage scenario. It does not describe return format or error cases, but these are not essential for a straightforward get operation. The description is complete enough for an agent to decide when and how to invoke it.

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 only parameter, 'slug', is fully described in the schema as 'Product slug (from search results)', and the main description reiterates that the tool identifies the product by its slug. The schema coverage is 100% and the description adds the source context (from search results), meeting the baseline for full parameter meaning.

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

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

The description clearly states a specific verb ('Return'), a resource ('complete detail for one product'), and identifies the input (slug). It also lists the exact fields returned, making the tool's purpose unmistakable and distinguishing it from sibling tools like search_products or get_product_catalog.

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

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

The description explicitly states when to use this tool: 'Use after search_products when one item needs full detail before quoting it.' This provides a clear trigger and context, though it only names one sibling (search_products) rather than all alternatives, leaving some implicit exclusion of other tools like get_product_catalog.

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 no annotations provided, the description carries the full burden of disclosing behavior. It explains the conditional behavior (no filter → category tree with counts; filter → filtered slice), which is meaningful context beyond what the schema alone conveys. It doesn't explicitly state read-only, but 'Return' and 'browsing' strongly imply a non-destructive 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 wasted words. The first sentence front-loads the core behavior, the second clarifies use cases, and the third names the alternative. Every sentence earns its place.

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

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

There is no output schema and no annotations, but the description gives enough context for an agent to select and invoke the tool correctly: it covers the main output shapes (filtered slice vs. category tree with counts) and points to the sibling for product-specific searches. It could mention return-field details or explicit read-only status, but for a browsing tool this is largely sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds only the high-level 'no filter' vs 'filter' distinction, which does not exceed what the schema implies. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific verb ('Return') and a clear resource ('catalogue') with two well-defined modes: a filtered slice or, with no filter, the full category tree with counts. It also explicitly contrasts with search_products, which helps an agent distinguish it from a sibling tool without opening schemas.

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

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

The description explicitly says when to use this tool ('for browsing and for questions about the catalogue's shape and size') and when not to ('Use search_products when the request names specific products'). This gives the agent concrete routing criteria rather than leaving inference up to 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?

With no annotations, the description carries the behavioral burden. It clearly discloses the return contents (line items, unit prices, line totals, grand total, desk contact details) and implies this is a calculation rather than a submission. It does not explicitly state that no order is created or discuss side effects, but the 'Returns...' phrasing strongly signals a read-only pricing 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 tight sentences: front-loaded verb and resource, then return summary, then routing guidance. Every sentence earns its place with zero filler 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 simple one-parameter tool with full schema coverage and no output schema, the description is nearly complete: it explains what the tool produces, when to use it, and when not to use it. It could additionally specify whether quantities must be positive integers or whether tax/shipping is included, but nothing essential to invoking 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%: the only parameter 'items' and its nested slug/quantity fields are already documented in the schema. The description adds context by calling it a 'wholesale quote' and 'straightforward priced list', but it does not add meaning beyond what the schema already provides, 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?

The description states a specific verb ('Build'), a resource ('wholesale quote'), and the exact inputs ('list of product slugs and quantities'). It also distinguishes itself from get_live_quote, making its scope immediately clear to an agent choosing between 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?

It explicitly says when to use this tool ('straightforward priced list') and explicitly names the alternative condition ('when a destination ZIP or an event date changes the answer, use get_live_quote instead'). This gives concrete selection criteria with no inference required.

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 no annotations, the description carries the behavioral disclosure burden. It discloses the conditional fallback behavior and explicitly promises never to fabricate a figure, which is valuable reliability context. It does not mention permissions, errors, or data freshness, but these are less critical for a simple lookup.

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. The primary behavior is front-loaded, the fallback is presented second, and the honesty guarantee earns its place as a final constraint.

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

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

For a one-parameter lookup with no output schema, the description covers the main outcome and the alternate outcome, plus a key reliability caveat. It could add a bit more detail about what the link points to or what 'tracked' means, but nothing essential is missing for invoking 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 for the single event_id parameter is 100%, so the schema already documents the parameter. The description adds no further format, example, or source detail for event_id, leaving it at the baseline value.

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 concrete verb ('Return') and identifies the resource ('recorded pipeline impact') plus the event-id key. It also defines the fallback result when no dashboard figure exists, making the tool's role unmistakable and distinct from the unrelated 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?

It clearly implies when to call: when pipeline-impact data for a given event_id is needed, and it explains what happens if the dashboard lacks the figure. It does not name alternative tools or explicitly say when not to use it, so it falls short of full 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?

With no annotations, the description must carry the safety burden. The verb 'Return' clearly indicates a read-only operation, and the content (capability card, policies, terms) implies no side effects. It does not explicitly state 'does not modify data,' but the retrieval nature is strongly implied.

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 somewhat verbose and redundant, repeating 'US' and 'United States' and listing many items in a single sentence. It could be tightened without losing clarity, but the structure is logically ordered and readable.

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?

The description provides a comprehensive list of what the returned capability card includes (legal entity, registrations, production model, etc.) and adds context about the vendor's origin and service area. Since there is no output schema, this enumeration effectively covers the expected response content.

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 has zero parameters, and the baseline for 0 params is 4. The description adds context about the vendor's history and shipping scope, which indirectly clarifies what data is available, but there are no parameter details to explain.

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

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

The description clearly states the tool's purpose with a specific verb ('Return') and resource ('vendor capability card'), and enumerates the contents. It also specifies the intended use case ('when a buyer or procurement agent is verifying the supplier'), making the purpose unmistakable.

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 explicit 'Use when' conditions (verifying supplier, checking national coverage, asking about delivery) that guide when to select this tool. However, it does not explicitly contrast with sibling tools like get_live_quote or search_products, so the differentiation is somewhat implicit.

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 no annotations, the description carries the full burden. It discloses the output (URL, 1200x630, no login), the indicative nature of position/scale, and even instructs the agent to say so when showing the image. It does not cover edge cases such as invalid logo URLs or error behavior, but the core behavioral profile is clear.

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

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

The description is front-loaded with the core purpose and each sentence serves a distinct function: purpose, inputs, output characteristics, limitation, and usage context. 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 tool with no output schema, the description adequately compensates by describing the return value and its properties. It also tells the agent when to invoke it and what to communicate to the buyer. Minor gaps, such as failure modes or error handling, prevent a 5.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces slug and logo_url but adds no new meaning for company_name or for behavior when logo_url is omitted; baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Render an indicative placement image showing a buyer their logo on a product, and return its URL.' It clearly distinguishes itself from siblings by framing this as an indicative preview, not a production proof.

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

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

It gives explicit when-to-use context: 'Use after search_products or get_product, once a buyer wants to see how something would look' and an explicit when-not: this is NOT a production proof. However, it does not name an alternative sibling tool for production proofs, only 'the desk issues the real one.'

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 no annotations, the description carries full burden. It fully discloses side effects: records buyer/programme/products, returns confirmation, opens a Corporate Store if products supplied, and explicitly states it does NOT place orders, take payment, or contact the buyer—a person reviews it.

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?

Description is reasonably concise (around 100 words) and front-loaded with the core action, followed by clarifying exclusions and usage condition. Some redundancy with schema descriptions but overall well-structured.

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

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

For a tool with 10 parameters and no output schema, the description is complete: explains purpose, side effects, what happens after submission (human review), and mentions the return of store_url. No missing context needed to call it correctly.

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

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

Schema descriptions already cover 100% of parameters with meaningful explanations (e.g., items sourced from search_products or generate_event_program). The tool description adds no extra semantic detail 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?

Clearly states the action (submit a programme request) and the resource (named-account desk), and explicitly distinguishes itself from siblings by noting it is the only write tool and listing what it does NOT do (place order, begin production, etc.).

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?

Provides explicit usage condition ('Use once the buyer has chosen products or a programme and wants to proceed') and contrasts with read-only sibling tools, making it obvious when to invoke this tool versus alternatives.

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

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

With no annotations, the description carries the full burden. It clearly states the return behavior ('Returns matching products with wholesale price, image, category and a virtual-proof link') and adds useful context about data scale (70,000+ items, 11,060 with live pages). It doesn't mention side effects or auth, but for a read-only search tool this is sufficient.

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 moderately long (4 sentences) but well-structured: it starts with the search purpose, moves to return details, then usage guidance, scale context, and finally synonyms. The synonym list is a bit extensive but adds practical value for matching user phrasing. No fluff or redundancy, so it earns a 4.

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?

The description provides sufficient context for an agent to decide when to use this tool: it explains the search scope, the returned fields, the scale of data, the alternative tool for browsing, and the variety of user terms that map to this catalogue. This covers all necessary decision-making information for a simple search tool.

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

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

Schema description coverage is 100% (all 7 parameters have descriptions), so the baseline is 3. The description's first sentence lists the filter dimensions but adds no new parameter-level meaning beyond what the schema already provides. Though it gives examples (e.g., 'nike backpack') in the query parameter, that is in the schema, not the tool description, so the description itself adds little parameter insight.

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?

Description clearly states a specific verb ('Search') and a specific resource ('the wholesale catalogue') with explicit filter dimensions (keyword, category, brand, price range, occasion). It also distinguishes itself from the sibling tool get_product_catalog by contrasting search vs. browsing, making the tool's purpose unambiguous.

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

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

The description explicitly says 'Use this for any request to find specific products' and directly contrasts with get_product_catalog ('For browsing the catalogue shape rather than searching it'), providing clear when-to-use guidance and an explicit alternative.

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

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

With no annotations provided, the description carries the full burden and handles it well. It discloses that the tool reads the live order record, handles missing records gracefully by returning a clear status and routing to the desk, and explicitly guarantees it never reports fabricated tracking state.

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 three concise sentences with the main action front-loaded. Every sentence adds meaningful information: the core function, the fallback behavior, and the accuracy guarantee. There is no filler or unnecessary 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 simple single-parameter tool with no output schema, the description covers the operation, the missing-record case, and the integrity guarantee. It could be slightly more explicit about what 'routes to the desk' means, but overall it gives an agent enough context to invoke 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 description coverage is 100% because the only parameter, order_id, has a description in the schema. The tool description reinforces that the ID is the lookup key but does not add format or additional semantic detail, 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?

The description uses a specific verb ('Return'), a clear resource ('logistics status of an order'), and a required identifier ('by its id'). This clearly distinguishes track_shipment from siblings like get_live_quote or get_product, which serve different purposes.

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 fetching live logistics status for a specific order, which provides clear context for when it should be used. It does not explicitly name alternatives or state when not to use it, so it stops 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.