CraftMe – Book craftspeople

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

Annotations already establish readOnly/non-destructive, and the description adds genuinely new behavior: results are in the studio's time zone, the searchable window starts tomorrow and caps at 90 days ahead with a 14-day-per-call limit. It also discloses that promotions are surfaced on returned times and applied automatically at booking, which is not derivable from annotations or schema.

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 compact sentences, front-loaded with the core definition and then the window constraints. The promotion sentence is slightly awkwardly phrased ('discount of the studio (percent, discounted price)') but every sentence 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?

With no output schema, the description does the necessary work of describing what comes back (start times, optionally a promotion with percent and discounted price) plus the timezone and window semantics. Only the ordering or count of returned slots is unstated, which is a minor gap for a 7-parameter read tool.

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

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

Schema coverage is 86%, so the schema already documents days, from_date, studio_id, employee_id and the time filters. The description largely restates the days limit and adds time-zone context, but says nothing about earliest_time/latest_time or the service_id/employee_id interaction beyond what the schema carries, 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?

The first sentence names a specific resource ('free start times') scoped to one service and one time zone, which is enough to distinguish it from get_studio and search_studios. It never explicitly contrasts itself with prepare_booking, but the verb+resource is 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?

Usage is only implied: the date window (tomorrow to 90 days, max 14 per call) tells the agent how to call it, and the promotion sentence hints this precedes booking, but there is no explicit 'use this before prepare_booking' or 'do not use this to check a specific employee's schedule outside the window' 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's useful addition is disclosing what comes back (bookable services with id, duration, price), which matters because no output schema exists, but it says nothing about error behavior for an unknown id or whether the services list is paginated or complete.

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 compact sentence with no filler, and the identifying resource ('one studio') is placed at the end for emphasis. It is slightly under-formed as a sentence fragment rather than a statement of action, 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?

For a one-parameter read tool with no output schema, the description does the main extra work by enumerating the returned fields. Combined with 100% schema coverage and clear annotations, an agent has enough to call it correctly; only failure modes and result-completeness semantics are 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 the studio_id property description already explains provenance ('from search_studios (or the handle from a profile link)'). The description adds no parameter meaning 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?

The description names the resource ('one studio') and enumerates returned fields (name, address, rating, bookable services), which is more specific than the title alone. But it is a noun phrase with no verb and no explicit statement that this is a single-record lookup keyed by id, and it never contrasts with search_studios, the sibling an agent would most likely confuse it with.

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 when-to-use guidance, no exclusions, and no named alternatives among find_free_slots, prepare_booking, or search_studios. The only hint at usage is the schema note that studio_id comes from search_studios, which is structured-field information rather than description 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?

Annotations already mark this readOnly/non-destructive, and the description usefully explains the side-effect boundary: the tool only checks and returns a link, while sign-in, deposit and studio terms happen outside the tool. It doesn't mention failure behaviour when the slot is taken or any rate limits, so it stops 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?

Two tight sentences with the core capability first and the crucial caveat second. Nothing is repeated and no sentence 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?

With no output schema, the description correctly discloses the return value (confirm_url) and the fact that booking is not final. For a small 5-parameter tool this is nearly sufficient, missing only what happens when the time is no longer free.

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% and the description adds no parameter-level detail such as date format, timezone handling or what employee_id means in group studios. Baseline 3 is appropriate since the schema largely 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?

The description gives a concrete verb and outcome: it re-checks availability for a specific time and returns a confirm_url. The 'Nothing is booked yet' clause clearly separates it from a real booking action, though it never names find_free_slots or get_studio directly.

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 the step after choosing a studio, service and time, since it takes those exact parameters. There is no explicit 'use this when...' or comparison against find_free_slots, which is the closest alternative.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds a genuinely useful behavioral fact: results are ordered nearest-first. It does not disclose pagination/truncation behavior beyond the schema's limit, or how it behaves when coordinates are absent, 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?

Two short sentences, front-loaded with what is returned and how it is ordered, then the optional filter. No filler.

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

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

For a six-parameter, all-optional lookup with no output schema, the description covers the essential intent, search modes and ordering. The remaining gaps (result shape, behavior with no location arguments, limit truncation) are minor for a search tool.

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

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

Schema coverage is 67% and latitude/longitude carry no descriptions at all; the description only loosely signals the location-vs-city choice and that service_query is an optional substring match. It adds a little meaning over the schema but does not compensate for the undocumented coordinate pair or the interaction between city and coordinates.

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 bookable craftsperson studios'), the platform, and the ordering ('nearest first'), plus an optional filter. It is clearly distinct from get_studio (single studio) and prepare_booking, though it never names those siblings 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?

'near a location or in a city' implies the two search modes and the description hints the service filter is optional, but there is no explicit when-to-use guidance, no mention of when to prefer find_free_slots or get_studio, and no statement about what happens when neither city nor coordinates are supplied.

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