Agent Salon SF

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

Annotations only declare it a safe, idempotent, closed-world read; the description adds the substantive caveats the annotations cannot: hours are published open/closed not live slots, candidate start times come from the staff schedule without subtracting existing bookings, and some may already be taken so they must be confirmed on the booking page. It also pins the response contract to GET /api/v1/availability?ref=.

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 negation of live availability and the routing to compare_options are front-loaded, and every clause carries information. The middle sentence is long and dense, stacking service matching, prices, durations, booking link and instructions into one run-on, which costs a little readability.

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

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

With no output schema, the description does the work of describing the returned fields: opening hours, matching offerings with prices and durations, booking link, step-by-step instructions, and candidate start times with their reliability caveat. Only the semantics of the time_after/time_before filters are left uncovered.

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 60% and the description adds meaning for ref (format source), date (opening hours on that date) and service (matching offerings). However, time_after and time_before are undocumented in both schema and description, so the description does not compensate for the coverage gap on those two filters.

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?

Opens with a specific verb+resource ('Published facts for one salon') and immediately negates the most likely misreading ('NOT live availability, NOT an extras-inclusive quote'). It names the sibling to use instead for decision-making, so an agent can separate it from compare_options without opening a 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?

Gives an explicit routing rule: use compare_options with salon=ref for service/budget/extras/date decisions, and use this tool for one salon plus a date. It also states the provenance of the ref ('from search_merchants'), which removes the main selection ambiguity.

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?

Goes well beyond the readOnly/idempotent annotations: no booking or hold is created, no provider-confirmed availability exists so date results are conditional, starting prices are not guaranteed quotes, deposit is advance payment rather than an added charge, and ordering is geographic/alphabetic rather than a quality signal. These are exactly the misconceptions an agent would otherwise form.

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 routing instruction and purpose are front-loaded, and the dense sentences carry real information. It is still a long block covering caveats, pagination, and edge semantics in one sweep, so a reader must parse several lines before reaching the operational rules.

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

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

For a 10-parameter decision tool with no output schema, the description pre-describes the return shape (options/uncertain/excluded groups with per-fact sources and dates, known subtotal, unresolved charges, next actions) and the limits of that data. Nothing an agent needs to call it correctly or interpret the result 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 baseline is 3, but the description adds meaning the schema does not: the pagination contract ('use next_offset across all three result groups') fills the undescribed offset parameter, and it clarifies that selected_addons means only user-requested extras since mandatory ones are auto-added. It does restate some enum content already present in the schema, keeping it short of 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 specific verb+resource ('Compare a supported service intent') and immediately frames the goal: 'START HERE for choosing a service under a budget, with extras, or on a date.' It explicitly separates itself from the name/address lookup sibling (search_merchants), so an agent can route without opening either 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?

Gives an explicit alternatives rule ('use search_merchants for name/address lookup; use this tool for the service decision') and negative guidance on unsupported filters (time-of-day, stylist, hair-length) that must be deferred to merchant confirmation. It also flags that require_availability cannot be satisfied today, which prevents a predictable misuse.

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 and discloses important non-obvious behavior: results come from the published staff schedule, existing bookings are not subtracted, some slots may already be taken, and confirmation is needed on the booking page. It also names result flags and explains freshness, which is strong transparency for a read tool.

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 most important caveat is front-loaded and the description is dense with useful information rather than filler. It is somewhat repetitive ('candidate start times' appears twice) and the long semicolon-heavy sentence could be easier to scan, but it is not bloated.

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 annotations, no output schema, and seven parameters, the description does well by explaining the non-live nature, result flags, and freshness. It still leaves gaps around pagination/limit behavior and precise time-window semantics, so it is strong but not fully complete.

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

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

Schema coverage is only 29%, so the description needs to compensate. It does clarify the core scoping model (one salon, one offering, optional stylist and date/time window), but it does not explain after/before formats or the limit parameter, leaving several optional parameters under-specified.

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 resource and scope: candidate start times for one offering at one salon, optionally one stylist and a date/time window. It also distinguishes the tool from compare_options and makes clear it is not live availability, which is the key sibling distinction.

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 not to use it ('NOT live availability') and names compare_options for budget/extras/date decisions. However, it does not explicitly route the agent to check_availability when live availability is actually needed, leaving one likely alternative 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 does real work: it discloses that the tool never books on the user's behalf (effectively a read/handoff operation) and that it returns steps and a pre-selection link. However, it omits link lifetime/expiry, whether the link is reusable, and any auth or failure behavior for a booking-adjacent tool.

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 return value, which is good. But the trailing clause about 'precision' is opaque and arguably hallucinated relative to the schema, so a sentence fails to earn 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?

No output schema exists, and the description does cover the return shape (URL plus remaining steps), which is the main gap filled. Still, with 4 params at 25% coverage and no annotations, the definition leaves the required salon argument and the phantom 'precision' notion unresolved.

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 25%, so the description must carry the load. It loosely maps 'service, stylist, and start time' to offering/stylist/start (and start's link to get_availability lives only in the schema), but never explains the required 'salon' parameter and introduces a 'precision' concept that does not exist in the schema, actively confusing 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 states a specific resource and outcome: the salon's own booking URL plus the exact remaining steps for a given service, stylist, and start time. It implicitly distinguishes itself from availability siblings by being the downstream booking step, though it never names an alternative explicitly. The odd phrasing about 'precision' muddies an otherwise clear purpose.

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 only implied — the agent must infer this is called after get_availability and when a user wants to actually book rather than browse. The 'never books on the user's behalf' line hints at a handoff flow but no when-not or alternative routing is given.

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 establish that this is a read-only, idempotent, non-open-world operation. The description adds substantial behavioral context by explaining that the response includes crawl_log with every source fetched or checked, timing and results, last_verified_at, per-field sources, verification status, and what was verified versus not verified. It stops short of discussing pagination, error behavior, or caching, but it goes well beyond the annotations.

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

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

The description is compact and front-loads the core purpose before listing detailed returned content. It is a dense single sentence, but each clause contributes useful information and there is no obvious 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?

There is no output schema, so the description must carry the burden of explaining what the tool returns. It does this thoroughly by enumerating the published facts, crawl_log contents, last_verified_at, per-field sources, verification status, and the distinction between what was verified and what was not. For a single-parameter read-only retrieval tool, this is complete enough to call 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% and the single ref parameter is already documented with an example. The description still adds value by clarifying the composite format '<city>/<vertical>/<slug>' and by stating that the ref should come from search results, which tells the agent where to obtain a valid 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 clearly states that this tool returns all published facts for one salon identified by a ref, and it names the key returned content such as crawl_log, last_verified_at, address, phone, hours, licence, registry, services, and booking link. It is specific about the action and resource, but it does not differentiate itself from the similar sibling tool get_salon.

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 usage by stating that the ref comes from search results, which gives useful context for when to call the tool. However, it does not explicitly say when to use this tool instead of get_salon, list_salons, search_merchants, or other sibling tools, nor does it describe 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?

With no annotations provided, the description carries the full burden and does real work: it declares the return format (markdown), and it discloses that every fact ships with a status tag and date and that start times come from the published schedule, which tells the agent to treat freshness/provenance as meaningful. It omits what happens on an unknown slug and any permission or rate-limit constraints, keeping it short of 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?

A single front-loaded sentence names the resource and format, then spends the rest on a compact enumeration of contents. No filler, and the most decision-relevant information leads.

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 must describe the return payload, which it does thoroughly by cataloguing every section of the record. The remaining gap is failure behavior and the slug's expected provenance, but for a read tool the description is nearly sufficient to call 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 50%: slug is documented in-schema while the format enum is not described. The description partially compensates by stating the output is markdown, hinting at the default format, but it never mentions that json is an available alternative, so the enum's practical significance remains undocumented.

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 resource ('Full record for one salon') and then enumerates exactly what that record contains (hours, services with price/duration/inclusions, stylists, policies, booking rules). That inventory makes clear it is the deep single-entity fetch rather than a list or a narrow lookup, though no sibling is named 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?

Usage is only implied: the breadth of the returned record suggests it is the tool for when a full salon profile is needed, and the sibling list makes the shallow alternatives (list_salons, get_stylist) guessable. There is no explicit when-to-use statement, no exclusion against lighter tools, and no prerequisite information such as whether the slug must come from list_salons first.

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 helpfully discloses the kinds of data returned, including 'specialty evidence with sources' and 'candidate start times from the published schedule,' which gives some sense of freshness and provenance. However, it omits error behavior for an unknown slug, whether the booking link is static, and any auth or rate-limit context.

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 is a single compact sentence fragment with no filler, and 'One stylist' is front-loaded. However, the colon-delimited field list reads like a data dump rather than a well-structured description, and the fragment lacks a clear action verb to anchor it.

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 lookup with no output schema, the description is reasonably complete about return contents. It still leaves out the meaning/behavior of the format parameter, error handling for invalid slugs, and any comparison with sibling tools, so it is adequate but not complete.

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

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

Schema description coverage is only 50%: the slug parameter is well documented in the schema (example and display-name fallback), but the format enum has no description. The tool description adds no parameter detail at all, so it does not compensate for the gap even though the enum values are largely self-explanatory.

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 identifies the resource as a single stylist and enumerates the specific detail it returns (salon, bookable status, services/prices, start times, booking link), which is much more specific than the tool name alone. It does not explicitly differentiate itself from siblings like get_salon or check_availability, keeping it from a 5.

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?

There is no guidance on when to use this tool versus alternatives such as get_salon, check_availability, or get_booking_link. Usage is only implied by the tool name and the list of returned fields; no exclusions or prerequisites 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?

With no annotations, the description carries the full burden and does well: it discloses ordering by depth tier, returned fields including availability basis/freshness and last_verified_at, and pagination defaults and limits. It does not describe permissions or rate limits, but for a read-only listing tool this is substantially transparent.

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 compact and front-loads geography and ordering before fields and pagination. The phrase 'ordered profiled, detailed, then listed' is grammatically awkward, but the overall structure is efficient and avoids waste.

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?

Because there is no output schema, the description usefully lists many returned fields and pagination behavior. But it does not explain response structure, total counts, or offset semantics, and does not guide the agent on when to use this list versus targeted siblings like get_salon or search_merchants.

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 only 33%, so the description must compensate. It adds the useful default limit of 50 and repeats the max of 200, and restates the depth enum values already documented in the schema. However, offset is named without explaining its pagination semantics or default, leaving one parameter underspecified.

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 resource and scope: salons in San Francisco, ordered by depth tier. It adds returned-field coverage (neighborhood, price range, stylist count, verification dates), so the agent knows what this list provides. It does not explicitly distinguish itself from siblings such as search_merchants or get_salon, keeping it below a 5.

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 browsing the salon catalog, but gives no explicit when-to-use guidance and names no alternatives. With sibling tools like search_merchants, get_salon, and compare_options available, the agent must infer that this is the broad listing tool rather than a targeted lookup or comparison tool.

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 exist, so the description carries the full burden and does so: it discloses that start times are unconfirmed schedule candidates (slotBasis, bookingsSubtracted false), that no salon currently has provider-confirmed availability, that prices are published menu/booking prices in USD with no extra add-ons, and that times are salon-local. It further explains failure behavior (hard constraints never relaxed; noMatch.reason and nearest).

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?

Purpose is front-loaded in the first sentence, but the body is a dense block that repeats the same availability caveat three times ('existing bookings are not subtracted, so some may already be taken', 'confirm on the booking page', availability_basis/slotBasis restated). The content is valuable but could be tightened substantially without losing 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?

For a 12-parameter, annotation-free tool with no output schema, the description usefully documents the response shape (unconfirmed list, noMatch.reason, nearest, offering.comparable). It falls short only on the undocumented query/limit/specialty/neighborhood parameters, which leaves some invocation decisions to guesswork.

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% across 12 parameters, so the description must compensate, and it only partly does: it gives semantics for haircut type, length, stylist, date/time window, budget (max_price) and require_availability, but never explains q, limit, specialty, or neighborhood. The enum values and defaults for those handled fields still come only 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?

States a specific verb and resource ('Find haircut offerings ... that satisfy ALL given constraints') and scopes it to profiled vs. listed salons. It also names the sibling it is not ('Use compare_options for a supported service with budget, extras or date'), so an agent can route without opening either 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 routes the comparison-with-extras case to compare_options and tells the agent to 'preserve any unsupported stylist/length/time requirements for merchant confirmation'. It also gives a conditional rule for require_availability=true (satisfied only by provider-confirmed availability), which is exactly the when-to-use guidance an agent needs.

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 cover safety (readOnly, idempotent, closed-world), and the description adds substantive behavioral context beyond them: default compact task summaries, the depth_note distinction between profiled and listed, hours_for_day being published hours rather than live slots, availability_basis values including unconfirmed candidates, and the blunt caveat that no salon currently has provider-confirmed availability. The return-shape enumeration is strong, though the field list is dense enough that a reader must parse carefully.

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 disambiguation sentence first, then capabilities, then return shape, then next-action routing — a sensible order. It is long and contains a very heavy single sentence enumerating return fields, but nearly every clause carries operational information rather than 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 23 optional parameters and no output schema, the description carries the return-value burden itself and does so: default summary vs full view, the key output fields, null semantics for unknown values, and the availability_basis/unconfirmed model. An agent can call this correctly and interpret the response without opening anything else.

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 87%, so the baseline is 3; the description still adds real semantics — what depth tiers mean, that max_price excludes extras and ignores starting prices, that require_availability rejects schedule-derived candidates, and that include_nearby yields match='nearby'. A few parameters (specialty, hair_length, stylist) get no description-level explanation, keeping it below 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 specific verb and resource (find San Francisco hair salons/barbers) with the exact search dimensions (name/street, neighborhood, service, date/time, online booking). It immediately delimits scope with 'Discovery and name/address lookup, not an extras-inclusive price decision,' which separates it from compare_options and check_availability by name.

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 routing rules: use compare_options when there is a supported service plus budget/extras/date, use check_availability for published hours/detail only, and call compare_options before selecting a budget option. It also instructs following next_action to confirm unresolved charges and real availability, leaving little to inference.

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