The Flowers Directory

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

Annotations already declare a safe, idempotent, read-only, open-world call, so the bar is lower. The description still earns credit by disclosing business rules not in structured fields: the 1:00 PM local-time same-day cutoff, Monday–Saturday operation, and that failures return a reason when known.

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?

Four sentences, front-loaded with the core question the tool answers, then scope, then timing rules, then failure behavior. Slight redundancy in restating the same-day cutoff and reason cases separately, but nothing is wasted.

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 needn't be spelled out, yet the description still tells the agent the result carries a reason field. For a two-param read-only availability check, the timing rules and failure semantics close every gap an agent would encounter.

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

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

Schema description coverage is 100%, so both zip (5-digit US ZIP) and date (YYYY-MM-DD, recipient local date) are already fully documented. The description adds only the framing that availability is per ZIP and date and the local-time-zone cutoff, which is a modest gain over the schema 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?

States a specific verb and resource (check delivery availability), and pins the scope precisely: per US ZIP code and one specific date, explicitly 'not per arrangement.' That scope statement also separates it from arrangement-level siblings like get_arrangement_details and search_arrangements.

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?

Implicit usage is clear from 'one specific date,' and the Sunday/past-date notes hint at when a check will fail. However, it never names an alternative such as next_available_delivery for finding a workable date, so the agent must infer the routing from sibling names alone.

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?

Adds substantial context beyond annotations: the 24-hour retention window, that it does nothing irreversible (no order, no payment), what exactly gets prefilled, and what the customer must still supply. This makes the non-idempotent, open-world write safe and predictable to reason about.

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 front-loaded sentences that open with the effect and lifetime before listing inputs and non-goals. Dense but every clause carries information; only the input enumeration mildly duplicates 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?

Given an output schema and annotations, the description covers the remaining gaps: lifetime of the saved data, safety boundaries, and division of labor between agent and customer. Nothing needed to invoke it 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% and every parameter already documents itself, including the zip→exact total relationship. The description groups parameters by purpose but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a precise verb+resource: saves delivery details for one arrangement for 24 hours and returns a checkout link with the cart prefilled plus a price breakdown. The 'does not place an order or take payment' clause separates it from order-placement flows, though it never names the close sibling get_checkout_link, leaving a possible ambiguity unresolved.

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?

Clear context for when to use it: when the customer wants a prefilled link rather than an immediate order, with the exact handoff described (customer adds street address, phone, pays). No explicit when-not or named alternative (e.g. get_checkout_link) is given, so it falls short of a 5.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, non-open-world lookup. The description adds meaningful behavioral context beyond the annotations: it identifies The Flowers Directory city pages as the source, notes that phone numbers are only included when listed, provides a last-verified date, and explains that ordering through The Flowers Directory may not involve one of the listed shops. That caveat is especially useful for preventing misuse.

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 wasted text. The core action and scope are front-loaded, and the important directory-listing caveat follows immediately. It is appropriately sized for a lookup tool.

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

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

The description covers the tool's purpose, data source, returned fields, and an important limitation about ordering and fulfillment. Annotations cover safety traits and an output schema exists, so the description need not explain return values. Minor gaps remain around how zip and city inputs interact, but the schema already documents that behavior.

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

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

Schema description coverage is 75%, with most parameters documented in the schema itself. The description adds no parameter-specific details and does not compensate for the undocumented limit parameter. Given that the schema carries most of the parameter meaning, a baseline score of 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 and resource: list florists in a US city from The Flowers Directory's city pages. It also states what the listing includes (addresses, phone numbers when available, last-verified date), making the tool's output scope clear. It does not explicitly name sibling tools, but it implicitly distinguishes directory lookup from ordering tools by clarifying that these are directory listings.

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 finding local florist listings in a US city, and the second sentence warns that these are directory listings rather than order-placement tools. However, it does not explicitly say when to use this versus siblings like check_delivery or search_arrangements, nor does it state exclusions or alternatives. Usage is therefore inferable but not fully guided.

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 already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful behavioral nuance beyond that: size is only present 'when the florist network publishes it', and the response includes tax-inclusive totals, a substitution policy and delivery terms — expectations an agent would otherwise have to discover by trial.

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 action and lookup key before the field inventory. The long run-on enumeration of returned fields partially duplicates the output schema, which is the only wasted effort.

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 tool with an output schema and full annotation coverage, the description supplies what is needed to invoke it correctly and know what to expect. Only the error/not-found path and the upstream source of the code are left unstated, which is a minor gap.

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

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

Schema coverage is 100% and the single parameter already carries an example ('T163-1A'). The description only restates that the lookup is by product code, adding no format, casing, or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return full details for one arrangement') with an explicit retrieval key (product code) and enumerates exactly what comes back. It reads clearly against the sibling search_arrangements, since the singular 'one arrangement by product code' signals a detail fetch rather than a search.

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 it to show a customer exactly what they are buying' gives a concrete decision context for calling the tool. It does not, however, say where the code comes from (presumably search_arrangements) or what to do when a code is unknown, so no exclusions or alternatives are stated.

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

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

Annotations already declare read-only, idempotent, open-world behavior, while the description adds important non-obvious context: opening the link adds the arrangement to the cart and opens the cart panel. No annotation contradiction; auth and rate-limit details are not covered but are not central here.

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 tool purpose, then pricing conditions, then the post-link checkout flow. There is no repetition, and the longer sentence carries useful behavioral detail.

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 not be explained in detail. The description covers pricing conditions and link behavior; it only omits failure/unavailable-date behavior and explicit sibling routing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional meaning for zip and date beyond the schema field descriptions: exact delivery fee, tax, total, and delivery availability with date. Code and client semantics remain delegated to 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: 'Return the purchase link for an arrangement plus a price breakdown.' It describes the checkout-link context well, though it does not explicitly name a sibling alternative, so differentiation is clear but not fully explicit.

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

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

Explains how ZIP and ZIP+date change the result, but does not say when to choose this tool over check_delivery, create_prefilled_checkout, or next_available_delivery. Usage is implied by the checkout purpose rather than directly routed.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description's job is to add semantics — and it does: it discloses that directory listings appear only for funeral_home and hospital types and only when city+state or ZIP is supplied. It doesn't explain how the guidance degrades without a location, which is the remaining gap.

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

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

Front-loaded with the core purpose in the first clause, with supporting enumeration after. The middle content list is dense but each item (venue rules, checkout field mapping, timing, search filters) tells the agent something it would otherwise have to discover by calling.

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?

Return values need not be described since an output schema exists, and the description adequately conveys scope, the required location_type, and the conditional territory-listing behavior. A fuller definition would note behavior when location_type is residence/business (no directory listing) and any validation failures.

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 baseline is 3; the description earns extra by explaining the interaction the schema cannot — that city/state or ZIP unlocks local venue listings and that listing type depends on location_type. It doesn't clarify what happens with city but no state, or how limit interacts, so not 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?

The description has a clear verb ('Return practical guidance') and a precisely enumerated resource (the six venue types) plus the content covered: arrangement suitability, venue rules, checkout fields, timing, and filters. It does not explicitly distinguish itself from the closest sibling, check_delivery, so an agent must infer the boundary between 'guidance' and 'delivery feasibility'.

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

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

Usage is implied rather than stated: this is the tool to consult when sending to a funeral_home, hospital, etc. The description does give a conditional trigger ('With a city and state or ZIP, also lists funeral homes... or hospitals'), but it never says when to prefer this over check_delivery or find_local_florists, nor any 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds real value beyond that: it enumerates what is returned (items, scheduled date, city, temporal status) and explicitly scopes out live tracking, which is the main behavioral surprise an agent could hit.

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 action and inputs, then the return payload, then the exclusion. Every sentence carries information; it is slightly longer than strictly necessary but 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?

An output schema exists, yet the description still usefully summarizes the returned fields, and it flags the absence of live tracking plus the fallback contact route. Nothing an agent needs to call this correctly or set expectations 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%, with both parameters self-documented, so the baseline is 3. The description corroborates the semantics (confirmation email, checkout email) but adds no syntax or format detail beyond what the schema already states.

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 ('look up an existing order') plus the exact identifying inputs (order number from confirmation email, checkout email). It implicitly separates itself from tracking tools by stating it does not provide live courier tracking, though it never names the sibling check_delivery explicitly.

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

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

Gives clear usage context: use when you have the order number and checkout email. It also sets an explicit exclusion ('does not provide live courier tracking') and redirects to the returned help phone/text numbers for confirmation, changes or cancellations. It stops short of naming alternative sibling tools by name.

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?

Adds real behavioral context beyond the annotations: a cap of 14 dates, a 1:00 PM local-time same-day cutoff, and a remaining-time-before-cutoff value. The annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so this supplementary timing logic is the value-add — though it doesn't say what happens outside the US or when no dates are available.

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

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

A single dense sentence that front-loads the result set size, then the three derived fields. 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?

For a one-parameter read-only tool with full annotations and an output schema, the description covers the search domain, output shape, and the timing rule that governs same-day results. Nothing an agent needs in order to call it 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?

Only one parameter and schema coverage is 100%, with the schema already documenting the 5-digit US ZIP pattern. The description adds little beyond 'available to a US ZIP code' — it does not say whether the ZIP must be the recipient's or how invalid/unserviceable ZIPs behave. Baseline 3 applies since the schema does the work.

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: lists upcoming delivery dates scoped to a US ZIP code, plus the earliest date and same-day feasibility. An agent knows exactly what it returns, though it never distinguishes itself from the sibling check_delivery, which likely overlaps on deliverability questions.

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

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

Usage is implied rather than stated: an agent can infer this is for 'when can this be delivered' questions, but there is no explicit when-to-use, when-not-to-use, or pointer to check_delivery as the alternative. Nothing is stated about what to do when the ZIP is not serviceable.

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, closed-world, so the safety profile is covered. The description adds real behavioral value on top: result cap of 20, best-match ordering, and the return payload including product code, photo URL, and total_before_tax defined as price plus the flat $19.99 delivery fee.

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 search scope before the return contract. It is dense but nearly every clause carries a distinct fact (filters, result cap, price semantics, structured attributes); a slightly tighter split of the long return sentence would improve scanability.

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 9-parameter, all-optional search tool with an output schema and full annotation coverage, the description is complete enough to call correctly: it explains the filter surface, the ranking/cap behavior, and the price semantics an agent must reason about. Nothing needed for a correct invocation is missing.

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

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

Schema coverage is already 89%, so baseline is 3, but the description adds genuine nuance beyond the schema — notably that budget is all-in (price + $19.99 delivery) while min_price is arrangement price only, and it broadens the occasion vocabulary beyond the enum list. That distinction materially affects correct parameter use.

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 ('Search The Flowers Directory catalog of fresh flower arrangements and plants') with the delivery scope ('US florist delivery'). The filtering dimensions named (occasion, color, flower type, arrangement type, size, budget, free text) let an agent separate this discovery tool from the detail/checkout siblings without opening any schema.

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

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

The description makes the usage context clear by enumerating the browsable dimensions and noting the return shape, so an agent knows this is the entry point for finding products. It does not, however, explicitly route to siblings ('use get_arrangement_details for full detail' or 'use check_delivery for serviceability'), so the when-not guidance is inferred rather than stated.

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