Neptune Cigars

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

Beyond the readOnlyHint annotation, the description discloses useful behavioral details: accepted state input formats, returned information categories (DTC shipping posture, age/ID rules, tax notes), and the 21+ adult signature requirement. This gives the agent a solid behavioral model without contradicting 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 four sentences with no filler: purpose first, then input format, return contents, and a key shipping constraint. Every sentence adds necessary 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 read-only tool with an output schema, the description is complete. It explains the input, the kind of output, and an important delivery rule. Nothing essential is missing 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?

Schema coverage is 0%, but the description fully compensates by explaining that the single 'state' parameter accepts a state name or 2-letter code and refers to a US state. This is the only parameter, and its meaning and accepted formats are fully covered.

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: 'Check whether Neptune Cigars can ship premium cigars to a US state.' This clearly distinguishes it from sibling search and product tools. The title and description align, and the intended operation is immediately evident.

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

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

The description gives clear context for when to use the tool: to determine shipping eligibility for a US state. It does not name alternatives or exclusions, but the sibling tools are search/product-related and not plausible substitutes, so no explicit exclusion is necessary.

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?

The readOnlyHint annotation already communicates that this is a safe read, and the description adds useful detail about the return payload, including taste profile, rating breakdown, price range, and knowledge-base description. It does not disclose edge-case behavior such as what happens if neither parameter is provided or if a name matches multiple lines.

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 compact sentences: the first defines the tool's scope and parameters, and the second summarizes what is returned. Every sentence adds value and there is no redundant restatement of the schema.

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

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

For a read-only lookup, the description, output schema, and readOnlyHint cover the common usage well. The main gap is that the schema marks zero required parameters, so an agent could call the tool without either line_id or name unless it infers the one-identifier precondition from the description.

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

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

With 0% schema description coverage, the description must compensate, and it does add key semantics: line_id should come from search_cigars and name is an alternative identifier. It does not specify whether exactly one is required, which parameter wins if both are given, or how name matching behaves, so the compensation is partial.

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 'Full details for one cigar line' and lists the lookup keys (line_id or name), so the verb, resource, and scope are immediately clear. It distinguishes itself from search_cigars by promising a single item's full details rather than a search result list.

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 says the tool takes a line_id from search_cigars or a name, which implies a look-up-after-search workflow. It does not explicitly rule out siblings like similar_cigars or search_products, but the single-item-details framing gives enough contextual 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?

readOnlyHint=true in annotations aligns with the search operation. The description adds useful behavior beyond the annotation: the return is capped at `limit` (max 25 lines), results are 'sorted by rating quality', max_box_price filters on the line's cheapest box, and min_rating reflects community ratings. This enriches the agent's expectations without contradicting the read-only hint.

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 uses one line per filter, which is scannable. The value lists (strength, origin, wrapper) are compact and each sentence earns its place, though the free-form filter list could be more structured at a glance.

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

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

For a 7-parameter search tool with 0% schema coverage, the description covers most filter semantics plus the limit cap and sort order. The output schema exists so return values need not be spelled out. The undocumented `query` parameter remains the main completeness gap.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely compensates: it enumerates allowed strength values, gives examples for origin and wrapper, explains max_box_price (cheapest box) and min_rating (1-5 community stars). However, the `query` parameter is never explained, which is a notable gap for a free-text search field.

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 ('Search premium cigar lines in the Neptune Cigars / Cigar Scanner catalog'), which is distinguishable from siblings like search_products (products broadly vs. cigar lines) and get_cigar_line (single-line retrieval vs. multi-line search). The scope is explicit and 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 clearly states that all filters are optional and explains the semantics of each filter, but it never tells an agent when to choose this tool over its siblings, such as search_products, get_cigar_line, or similar_cigars. No exclusions or alternative-routing guidance is provided.

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 provide readOnlyHint, so the description adds meaningful behavioral context: it returns live sellable items with exact packaging, current price, stock availability, and a direct URL, and it is meant for name-based stock lookups after line selection. It does not disclose pagination or query matching details, but output schema and readOnly hint reduce the burden.

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, each earning its place: purpose, return detail, and usage guidance. No redundancy or 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?

The description is complete enough for an agent to invoke correctly: output schema covers return values, readOnlyHint covers safety, and the name-query + search_cigars-first workflow covers selection. Minor omissions are limit semantics and more precise query matching behavior, but these are not blocking.

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

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

With 0% schema description coverage, the description must compensate. It explains query as searching by name and in_stock_only through 'find what's in stock,' but it never mentions the limit parameter's behavior, leaving a gap.

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

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

The description uses a specific verb and resource: 'Search buyable products (SKUs) on neptunecigar.com by name.' It also clarifies the output (live sellable items, exact vitola/packaging, price, stock, URL) and explicitly differentiates from search_cigars by prescribing it as the prerequisite step.

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

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

It gives a clear workflow: 'Use search_cigars first to pick a line, then this to find what's in stock.' This tells an agent when to use this tool versus the main alternative, and the 'by name' qualifier further narrows selection.

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, so the safety profile is covered. The description adds behavioral context by explaining the fallback logic ('profile matching (same strength + origin, comparable rating)'), which clarifies how results are generated. This goes beyond the annotation without contradicting 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?

The description is tightly written in two sentences. The main purpose is front-loaded, and the addition of algorithm details is relevant without excess. Every sentence contributes value.

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 read-only tool with an output schema present, the description adequately covers the purpose and method. It does not explain return format, but that is handled by the output schema. A slight gap is that it doesn't mention any constraints (e.g., what happens if no similar lines are found), but overall it is 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 coverage is 0%, so the description must clarify parameters. It does clarify that 'name' refers to the 'given line' (by saying 'a given line'), but it does not mention the 'limit' parameter or its meaning (though it has a default of 8, its purpose is not explained). This is partial compensation, hence a 3.

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

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

The description states the tool finds 'Cigar lines similar to a given line', which is a specific resource (cigar lines) and action (find similar). It is clearly distinct from siblings like search_cigars (generic search) and get_cigar_line (specific line retrieval), and the title reinforces this.

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 an explicit use case: 'for "if you like X, try Y"'. This tells the agent when to trigger it. However, it does not mention when not to use it or explicitly point to alternatives, 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.