Pinflower — flowers in Prague

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

Annotations only flag destructiveHint/openWorldHint; the description adds the substantive behavior: a full refund of any paid amount, the two-step confirmation flow, and that a 6-digit code is sent to the e-mail the order was placed with. It also discloses the eligibility constraint that determines whether the cancel succeeds at all.

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

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

Front-loaded with the trigger condition, then rules, then the two-step mechanism, then exclusions. Every sentence carries distinct information; there is no filler or restatement of the title.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining gaps: eligibility, refund outcome, the code-delivery step, and unsupported operations. An agent has everything needed to execute the two-call sequence 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 67% (order_ref is undocumented there). The description compensates by explaining the sequencing semantics: order_ref + confirm=true issues the code, then order_ref + code completes the cancel. That flow meaning is not derivable from the schema alone, though it never describes the order_ref format.

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

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

States a specific verb and resource ('cancel an order placed here') and immediately scopes the trigger to an explicit buyer request. None of the siblings (check_delivery, create_order, get_order_status, etc.) perform cancellation, so the agent can route unambiguously.

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

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

Gives explicit when-to-use ('buyer explicitly asks to cancel') plus eligibility windows (free until florist confirmation; later-day orders until the cut-off) and a when-not ('changing items, delivery details or the delivery time is not supported'). It stops short of naming which sibling to use for those unsupported changes, so the routing half 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 already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered without help. The description usefully discloses the overlap with bouquet search results and that the place is taken verbatim, but says nothing about auth, rate limits, or failure behavior; an output schema exists so return format is not needed. This is modest added value over 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?

Front-loaded with the usage trigger, followed by two short supporting sentences; the total is appropriately sized for the tool's scope. The "Takes the place as the buyer said it" sentence is slight redundancy against the schema but cheap and reinforcing.

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

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

Covers purpose, triggering questions, ordering relative to bouquet selection, and the overlap with search results, which is the main ambiguity an agent would face. Since an output schema exists, the lack of return-value detail is not a gap.

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

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

Schema description coverage is 100%, so the schema already documents `where`, `date` and `locale`. The description's only parameter-relevant statement, "Takes the place as the buyer said it," repeats the schema's own wording rather than adding format or edge-case guidance. Baseline 3 is correct.

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

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

Names a specific action (check delivery availability/cost/timing) for a specific resource (a place in Prague), and the phrasing "whether Pinflower delivers to a place in Prague, how much delivery costs, how soon it can arrive" enumerates the exact questions it answers. It also distinguishes itself from sibling pinflower_search_bouquets by noting search results already embed this data.

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

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

Gives an explicit trigger ("Use this when the buyer asks whether...") plus a sequencing constraint ("before choosing a bouquet") and a de-duplication rule ("Bouquet search results already include this for their place"), which implicitly tells the agent not to call it redundantly. It stops short of naming the alternative tool explicitly or stating other when-not conditions.

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 annotations say this writes (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds real behavior on top: nothing is charged here, the florist is not told until the buyer pays, and a mismatched confirmed_total_czk aborts the creation. It also explains the safety retry semantics of order_intent and the 0 Kč care_reminder, none of which the annotations convey.

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

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

It front-loads the decision condition well, but then turns into a long single-paragraph inventory of fields that the schema already documents at 77% coverage. The core value (when to call, what aborts, what happens with payment) is buried inside that list.

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 22-parameter, nested, open-world write operation with an output schema, the description covers purpose, preconditions, failures and side effects sufficiently. The return values (payment link vs. re-quote breakdown) are described as well, so nothing an agent needs in order to call it safely 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?

The description adds cross-field rules the schema does not state: recipient name/phone are required for ask_recipient and agree_with_recipient, billing address is required above 10 000 Kč, add-ons are per bouquet, and care_reminder is free and offered once. Some of this restates schema descriptions verbatim, but the conditional dependencies are genuine added 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 first sentence states a specific verb and resource (creates the order) plus its precondition (the buyer has agreed to the quoted total) and its outcome (returns the secure payment link on pinflower.cz). That clearly separates it from the sibling pinflower_quote_order, which only quotes.

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 guidance tied to the quote being accepted, and implicit but clear when-not guidance: if the total changed, nothing is created and the new breakdown comes back instead. It also names the concrete prerequisites and alternatives (address_mode ask_recipient vs known address, time agree_with_recipient, custom bouquet vs bouquet_id), so the agent can decide between the options without guessing.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: whether the returned price is exact depends on supplying a street address versus falling back to the shop's typical fee, and the lookup is scoped to one bouquet per 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 sentences, with the usage trigger front-loaded and the returned fields following. The long parenthetical about delivery_fee_exact is slightly convoluted but every clause carries information; nothing is padding.

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

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

An output schema exists, so return structure need not be spelled out, and the description still summarizes what comes back. Combined with the annotations and near-complete parameter descriptions, an agent has enough to invoke the tool correctly; only explicit alternative routing 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 80%, so the schema already documents date, where, locale and fulfilment formats. The description nonetheless adds meaning by tying the 'where' parameter to price precision (exact fee for a street address, typical fee otherwise) and by noting bouquet_id must be the value as shown in search results.

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 and resource (fetch one bouquet's details from search results) and enumerates the returned content: contents, size, photos, florist rating, price with delivery, and arrival times. 'Covers one bouquet at a time' cleanly distinguishes it from the bulk-oriented pinflower_search_bouquets sibling.

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 clause gives a clear trigger: 'Use this when the buyer is interested in one bouquet from the search results.' It implicitly routes the agent from search to detail and notes the single-bouquet scope, but never explicitly names the alternative to use for multiple bouquets or when not to call it.

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

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

Annotations already cover read-only, non-destructive, idempotent and closed-world, so 'Read-only: it changes nothing' adds nothing. The real added value is the prerequisite disclosure that the order_ref comes from order creation, which tells the agent where to source the required input.

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

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

Two tight sentences: usage trigger first, prerequisite and safety second. The trailing 'Read-only: it changes nothing' is slightly redundant with the annotations but does little harm.

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 two-parameter read tool with an output schema and full annotation coverage, the description supplies the trigger, the input provenance and the safety profile. Nothing the agent needs before calling 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 only 50%: locale is documented in the schema, but order_ref is bare there. The description compensates by explaining that order_ref is the reference returned at order creation, which is meaningful provenance beyond the schema.

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

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

States a specific verb and resource ('get order status') and enumerates the states it reports (paid, confirmed, on the way, delivered), so the agent knows exactly what the call answers. It does not, however, differentiate itself from the sibling pinflower_check_delivery, which appears to overlap in scope.

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

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

'Use this when the buyer asks what is happening with an order placed here' gives a clear trigger condition and a scope qualifier (orders placed here). No explicit when-not or sibling exclusion against check_delivery is provided, 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.

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

Annotations flag this as non-read-only and destructive (destructiveHint=true), yet the description frames it purely as returning a link and never discloses what side effects or invalidation may occur — a real gap for a destructive tool. It does add useful behavioral context (idempotency in prose, the paid/cancelled guard) beyond the annotations, so it is not a contradiction, just incomplete.

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

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

Front-loaded with the usage trigger followed by the return semantics and exclusion, delivered in a single dense sentence with no filler. The dash-clauses are slightly run-on but every clause carries information.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. However, for a destructive, one-param tool with zero schema coverage, the description leaves the order_ref format and the destructive side effects unexplained, so it is only 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?

With 0% schema description coverage, the description must carry parameter meaning, but it only states 'Needs the order_ref' — naming the parameter without supplying format, source, or example. It confirms requiredness but adds essentially no semantics over the bare schema.

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

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

The description states a specific verb+resource (returns the order's payable link on pinflower.cz) and clarifies that it re-serves the same link while the order is open, guarding against the 'new' in the name. It doesn't explicitly distinguish itself from a sibling like pinflower_get_order_status, which could plausibly also surface order data.

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

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

Explicitly names the triggering condition ('buyer has not paid yet and the payment link expired or got lost') and the exclusion ('Not for paid or cancelled orders'), which is strong routing guidance. It stops short of 5 because no sibling alternative is named for the paid/cancelled case.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavior: what the price is composed of (bouquets, add-ons, launch discount or promo code, delivery fee), the Czech tax rule requiring a billing address above 10 000 Kč, and the caveat that the total is valid for exactly these details. It also discloses the return shape (breakdown, total, terms link, order_intent).

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 usage trigger is front-loaded well, but the body is one long run-on enumeration of parameters, and the no-side-effect point is repeated three times ('without creating anything', 'it creates nothing', 'creates nothing'), which costs space without adding 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 an 18-parameter, deeply nested pricing tool it covers the conditional dependencies (recipient required for surprise delivery, billing address threshold, company IČO) that an agent would otherwise get wrong. Return values need not be explained given the output schema, though locale and marketing_opt_in are never addressed.

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 18 params at 72% schema coverage, the description still contributes rule-level meaning the schema cannot: several bouquets only from ONE florist, address_mode 'ask_recipient' requiring recipient name and phone, time 'agree_with_recipient' being delivery-only, and care_reminder being free and delivery-only. It leaves locale, unit, courier_note and marketing_opt_in unmentioned, but those are minor.

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

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

States a specific verb and resource — prices/quotes the order exactly as checkout will charge it — and explicitly distinguishes itself from order creation ('without creating anything', 'it creates nothing'), which separates it cleanly from pinflower_create_order in the sibling 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?

'Use this when the buyer has chosen what to order and you have the details' gives an explicit trigger condition, and it points to search as the source of bouquet_id. It never names the follow-up tool (create_order) as the next step, so the routing to alternatives is implied rather than stated.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description adds genuinely non-obvious behavior: results render to the buyer as a carousel, results are ordered by the storefront's recommendation, and with no date/deliver_by every result carries its earliest time. That is real context beyond the structured fields.

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

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

Scope, return contents, input shape, side effect and exclusions are packed into four dense sentences with the most decision-relevant information (Prague, concrete bouquets, carousel) front-loaded. No sentence is filler.

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

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

With 18 params but an output schema and rich annotations, the definition still covers what an agent needs: eligibility guarantees, ordering, the empty-date fallback, the carousel side effect, and geographic bounds. Nothing material is missing 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 94%, so the baseline is 3, but the description adds a useful framing of the input groups ('free text, occasion, budget, where, date and a deliver-by time') that helps an agent map buyer speech onto parameters. It doesn't add per-parameter syntax beyond the schema, keeping it below a 5.

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 concrete verb and resource ('returns only bouquets that can really arrive at the given place and time') and pins the geography to Prague, immediately separating it from sibling tools like get_bouquet or quote_order. An agent can tell exactly what this returns without opening the schema.

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

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

Explicitly frames the trigger ('Use this when the buyer wants flowers delivered in Prague... and you need concrete bouquets') and gives exclusions ('Not for general flower advice or for orders outside Prague'). It does not name a specific sibling to use instead for detail/advice, so it stops just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description still adds useful context: answers are sourced from the shop's own pages and returned with links, which tells the agent the response is authoritative and link-bearing rather than a generic generation.

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

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

Three sentences, front-loaded with the trigger condition, then the coverage list, then the exclusion. The enumeration is long but every item is a distinct routing cue rather than filler, and there is no redundant or decorative prose.

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?

An output schema exists, so the description need not explain return values. For a read-only informational lookup, what an agent needs (when to call it, what topics it resolves, what it does not resolve, and that responses include links) is all present.

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 single parameter (locale) is fully documented in the schema, including its enum values and default. The description adds nothing about locale or language behavior, so per the high-coverage baseline this is a minimum-viable 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?

States a specific resource (Pinflower's own informational pages) and enumerates exactly what it covers: payment timing, delivery area/fees, anonymous delivery and card message, absence handling, returns/complaints, and contact. It explicitly excludes bouquet availability, which cleanly separates it from pinflower_get_bouquet and pinflower_search_bouquets.

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?

Opens with an explicit trigger ('Use this when the buyer asks how ordering works...') followed by an exhaustive topic list, and closes with a negative scope ('Does not cover bouquet availability') that routes the agent elsewhere. Both when-to-use and when-not-to-use are stated, leaving nothing to inference.

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