boulevard

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

Annotations already declare destructiveHint=true, so the mutation risk is covered structurally. The description adds that the tag must pre-exist and which entities are taggable, but does not disclose idempotency (what happens if the tag is already on the record), reversibility, or that no un-tag counterpart is offered here. Useful context, but modest beyond 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?

Two short sentences; the action and its target come first, the upstream dependency second, and the raw GraphQL mutation name is appended compactly. 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 two-parameter mutation with no output schema and annotation coverage of the destructive flag, the description supplies prerequisite and target scope plus the underlying GraphQL operation. It is nearly complete; only duplicate-application behavior is unaddressed.

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%, with both tag_id and entity_id format examples (URN patterns) documented in the schema. The description only reinforces that tag_id must be an existing tag; it adds no syntax or constraint detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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 (apply) plus the resource (an existing tag) and the target (taggable records such as clients or appointments). It also names the sibling boulevard_list_tags as the source of tag ids, so an agent can distinguish it from the list/query tools 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?

Clearly signals the prerequisite flow — the tag must already exist and come from boulevard_list_tags — and scope-limits targets to 'taggable records such as a client or appointment'. It does not state when not to use it or what to do if the tag is already applied, so it stops short of full routing 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 supply destructiveHint=true, but the description adds no behavioral detail beyond the dedup workflow — it does not say what happens if a duplicate exists (reject vs merge), whether specific scopes/auth are required, or what the call returns. The duplicate-check guidance is genuine operational context, which is worth credit, but the disclosure remains thin.

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 the action and then the operational caution. The trailing "GraphQL: createClient." is minor filler for an agent that only needs the tool name, but it costs little space.

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 and all 7 parameters optional, the description does not state what a successful creation returns (e.g., a new client id) nor that the inputs are all optional, leaving the agent to infer the response. It is adequate for invocation but not fully complete given the absent return contract.

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% for all 7 fields (dob, email, pronoun, names, external_id, mobile_phone) including formats and the E.164/date patterns, so the schema carries the parameter semantics. The description adds no field-level meaning, so the baseline of 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 ("Create a new client profile") and implicitly distinguishes itself from the retrieval/mutation siblings boulevard_get_client, boulevard_list_clients and boulevard_update_client. It even names the underlying GraphQL operation (createClient), making the intent 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?

Provides an explicit precondition: check boulevard_list_clients by email or phone first to avoid a duplicate. That is clear, actionable guidance tied to a named sibling. It stops short of stating when-not-to-use (e.g., use boulevard_update_client for existing clients), so it is not a full when/when-not/alternatives statement.

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

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

Annotations only supply destructiveHint=true and a title, so the description usefully adds the visibility scope (internal, staff-only, not client-facing), which is real behavioral context an agent needs. However, it does not explain the destructiveHint on what is nominally a create operation, nor mention auth/permission requirements, leaving a notable 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?

Two tight sentences: purpose and visibility first, GraphQL mapping second. No filler, nothing repeated from the schema, and the most decision-relevant information is front-loaded.

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

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

For a simple two-parameter create tool with no output schema, the description covers purpose, target resource, and visibility adequately. It stops short of stating where the note surfaces or whether it is editable/deletable, but nothing critical to invoking it 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 description coverage is 100% – both client_id (with its urn:blvd:Client:<uuid> format) and text are fully documented in the schema. The description adds no format or constraint detail beyond that, 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+resource ("Add an internal note to a client's profile") and disambiguates itself from note-like siblings such as boulevard_add_tag by specifying the target (client profile) and the nature of the content. The GraphQL operation name is a bonus that makes the action unambiguous.

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

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

The examples ("formulas, preferences, allergies") and the "visible to staff" qualifier imply when a note is appropriate, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as boulevard_update_client or boulevard_add_tag.

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 destructiveHint=true annotation carries the safety profile, so the bar is lower. The description adds real behavioral context beyond the annotation: the block makes the slot unbookable and is non-recurring. It does not disclose permission requirements, whether an existing appointment on that slot is affected, or any conflict/precondition handling for a mutation.

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 short sentences with no filler, and the core action plus its effect on bookability are front-loaded before the scoping constraints.

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 6-parameter mutation with full schema coverage, no output schema, and a safety annotation present, the description covers purpose, effect, and the one-off constraint adequately. It stops short of prerequisites (permissions, location/staff validity, conflict behavior), which is the only meaningful 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 every parameter (title, reason enum, duration bounds, staff_id URN format, start_time ISO 8601, location_id source) is already documented in the schema. The description restates the location/staff scope but adds no format, default, or interaction 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 specific verb and resource ('Block time on one staff member's calendar at a location') and defines the artifact in concrete terms (a break, meeting or personal time). The clause 'so it cannot be booked' plus 'One-off only' cleanly separates it from the appointment-creation and recurring-schedule tools in the sibling set.

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?

'One-off only' gives an implicit usage boundary (single occurrence, not recurring), which is the extent of the guidance. It never names an alternative or states when NOT to use it (e.g., when an appointment or shift should be created instead), so the agent must infer the choice.

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

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

The readOnlyHint already signals a safe read, and the description goes beyond annotations by describing the return payload in detail (time, state, notes, client, each service with staff and price in cents, cancellation details, tags) — effectively compensating for the absent output schema. It stops short of covering not-found/error behavior, so it is not fully 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?

Front-loaded with the verb and resource, then a compact em-dash list of return fields; no wasted sentences. The trailing 'GraphQL: appointment.' is mildly cryptic jargon, which keeps it just short of a 5.

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 no output schema, the description supplies the return shape and the annotations cover read-only safety, leaving little an agent needs to know to call it. The only real gap is error/not-found 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?

With one parameter at 100% schema description coverage, the schema already documents the appointment_id format (urn:blvd:Appointment:<uuid>). The description's 'by id' adds no syntax or format detail beyond that, 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 (Fetch) and resource (one appointment) and explicitly scopes it to a single record by id, which distinguishes it cleanly from the sibling boulevard_list_appointments. It even enumerates the returned facets, so an agent knows exactly what this call is for.

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 'by id' phrasing implies the tool is for when you already have an appointment id, but it never states when to choose this over boulevard_list_appointments or what to do if the id is unknown. Usage is inferable rather than stated, so this sits at the minimum-viable level.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description still adds value by disclosing credential-scoping semantics ('the credentials act for'), flagging the call as 'cheap', and listing the returned attributes in the absence of an output schema. It does not describe failure behavior when credentials are invalid, which is the main 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?

Three compact clauses, front-loaded with the verb+resource, then the return fields, then the use case, then the GraphQL mapping. No sentence is filler and the GraphQL note gives implementation traceability cheaply.

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 zero-param, read-only tool with no output schema, the description compensates by naming the returned fields and the credential scoping, so an agent can call it without further research. It is short of perfect only in not stating what happens on auth failure, which matters for a tool explicitly recommended as a setup check.

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 tool takes zero parameters, which sets the baseline at 4. The description correctly implies no input is needed — it operates purely off the credentials in context — so nothing further is required here.

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 ('Fetch the Boulevard business') and disambiguates scope as 'the business the credentials act for', which distinguishes it from get_client, get_order, get_appointment and the list_* siblings. It even enumerates the returned fields (name, timezone, address, phone, website), so an agent knows exactly what it gets without opening anything else.

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?

'A cheap way to confirm the setup works' gives a concrete when-to-use scenario (credential/setup verification), which is a clear call condition. It stops short of any when-not guidance or naming an alternative, though no sibling competes for the same resource, so the routing risk is low.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the retrieval payload (contact details, appointment count, balance in cents, alert, tags, notes), which is useful, but it discloses nothing about error behavior, missing/invalid ids, or permissions. Adequate, not rich, against an annotation that already covers safety.

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 the essential scope front-loaded, followed by a short GraphQL type mapping. No filler; slightly dense in the field enumeration but nothing 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, enumerating the returned fields is a genuinely useful addition and largely covers what an agent needs for a one-parameter read tool. It stops short of error/not-found behavior, leaving 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's description already supplies the URN format example, so the schema carries the semantics. The description only restates "by id" and adds no format or constraint detail beyond it — baseline 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 verb and resource ("Fetch one client by id") and enumerates the payload, which cleanly distinguishes it from boulevard_list_clients and boulevard_update_client. An agent can identify the tool 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?

The phrase "by id" implies a lookup use case, but no alternative is named and there is no stated when/when-not guidance (e.g. use list_clients when the id is unknown). Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description still adds real behavioral context by disclosing the response contents and the unit convention ('amounts in cents'), which an agent would otherwise have to discover at runtime.

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 leads with verb, resource and scoping, then lists the returned entities. No filler and no repetition.

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 usefully compensates by naming the returned aggregates and the cents convention. It stops short of covering error behavior for a missing or malformed id, which is the only remaining gap for a single-resource fetch.

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 order_id parameter is fully documented in the schema, including the urn:blvd:Order:<uuid> format. The description only restates 'by id', 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 specific verb and resource ('Fetch one order by id') and enumerates the payload (totals, line items, services, products, gratuity, gift cards), which cleanly distinguishes it from the sibling boulevard_list_orders. The trailing 'GraphQL: order' also maps it to the underlying operation.

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?

'By id' implies the precondition that you already hold an order id, but the description never states when to reach for this versus boulevard_list_orders or what to do if the id is unknown. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description usefully adds that each appointment carries its client, services, staff, state and cancellation, and maps the call to the underlying GraphQL 'appointments' field — real context beyond the structured data, though it says nothing about pagination or volume limits.

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: the primary scope (location) leads, optional refinements follow, and the return-content note closes. No filler or redundancy.

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 compensates by enumerating the fields each appointment returns. Combined with the 100%-covered input schema and readOnly annotation, an agent has enough to call it correctly; only pagination behavior and cardinality limits are left unstated.

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 all five parameters (after, first, query, client_id, location_id) are already documented in the schema with examples and formats. The description only restates the client and query filters at a higher level, adding no syntax or constraint detail — 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 (List) and resource (appointments) plus its scope: one location, optionally one client, with a query filter. It contrasts implicitly with boulevard_get_appointment via the list/get distinction, but never names the sibling or explicitly delimits the boundary.

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 invocation: it is location-scoped, with optional client narrowing and query-based filtering such as date range or staff member. No when-not guidance or named alternatives (e.g. use get_appointment for a single record), 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?

readOnlyHint=true already declares this is a safe read, so the lower bar applies. The description adds only the GraphQL backing query ('GraphQL: clients') and no behavioral context such as pagination behavior, result limits, or ordering; the pagination contract lives in the schema instead.

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 that names the operation before listing the variants; the trailing 'GraphQL: clients' is a compact backend mapping hint with no 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?

For a read-only list tool with 100% schema coverage and no output schema, the description plus schema covers what an agent needs. Ordering of returned results and whether the GraphQL mapping affects call shape are the only unaddressed details.

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 every parameter is already documented, including the QueryString grammar. The description's inline examples ('name = "Jane Doe"', mobilePhone) restate query-syntax territory the schema already covers, so 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?

States a specific verb+resource ('List the business's clients') and enumerates the three search modes (email, id list, query). This clearly separates it from the singular boulevard_get_client, though it never names that sibling 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?

Explains when each retrieval mode applies ('find them by email, id list, or a query') with concrete query examples, giving the agent clear routing context. It stops short of naming alternatives or stating exclusions (e.g. use get_client for a single known id).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. With no output schema, the description adds real value by naming the returned fields (id, name, timezone, address), and the "GraphQL: locations" note tells integrators where to look for deeper semantics. It doesn't discuss ordering or pagination behavior beyond what the schema states.

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, front-loaded sentences that each carry distinct information: what is returned, and why an agent should call it. The trailing GraphQL pointer is compact and useful 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?

For a two-parameter, read-only list tool with no output schema, the description covers purpose, returned fields, and its role as a dependency for other tools — enough to invoke it correctly. Pagination details live in the schema, so nothing critical is missing, though result ordering/size guidance is absent.

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 both pagination parameters (after, first) are fully documented in the schema, including the cursor source and the 1-100 range. The description adds nothing about parameters, so the baseline of 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 ("List the business's locations") and even enumerates the returned fields (id, name, timezone, address). An agent can distinguish it from the other list_* siblings (appointments, clients, orders, products, services, shifts, staff, tags) purely by the resource named.

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 sentence "Most other tools need a location id from here" gives clear context for when this tool is the right first call, effectively positioning it as the root/prerequisite lookup. It does not name a specific alternative or an explicit when-not condition, which keeps it 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=true, so the safety bar is low. The description adds genuine value by disclosing the returned data model (status enum values, client, price in cents, interval, term, next charge date), which matters since no output schema exists. It stops short of describing pagination or result limits.

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 front-loads the resource and the field list, with a short GraphQL mapping note appended. No filler or redundancy.

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

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

For a read-only list tool with full schema coverage and readOnlyHint annotations, the definition is nearly complete, and the field enumeration compensates for the missing output schema. Only the absence of pagination/scope notes keeps it from being 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 description coverage is 100% (after/first are fully documented in the schema), so the description does the minimum here. It adds no cursor or page-size semantics beyond what the structured fields already provide. 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?

States a specific verb ('List') and resource ('client memberships sold by the business'), and even enumerates the returned attributes. This clearly distinguishes it from sibling list tools such as boulevard_list_clients or boulevard_list_orders.

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 by the resource name (list memberships), but there is no explicit when-to-use, no exclusions, and no mention of filtering or pagination behavior. An agent can infer its purpose but gets no routing guidance versus adjacent tools.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior context beyond that: totals are expressed in cents and the specific total fields (subtotal, discount, tax, gratuity, total, refunds) that come back, which compensates for the absent output 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?

A single dense sentence with the core action front-loaded and the return-field detail in a tight parenthetical. Nothing is wasted or redundant.

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

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

For a read-only, fully documented list tool with annotations covering safety, the description is nearly complete, and it usefully previews return fields despite there being no output schema. It only lacks guidance on relationship to the singular get_order 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 description coverage is 100%, so the schema already documents after, first, query, and location_id in detail. The description's filter examples add minor framing but no syntax or format beyond what the schema provides, 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 a specific verb and resource ('List checkout orders') and scopes it to one location, plus enumerates the returned totals. It implicitly contrasts with the singular boulevard_get_order, though it does not name that sibling 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?

It says filtering is optional and gives examples ('closedAt range or clientId'), which implies when the tool is useful, but it never states when to prefer it over boulevard_get_order or how to choose between the two. Usage is implied rather than 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds useful context beyond that — the returned field set, that price/cost are in cents, and that inactive products are excluded by default — but says nothing about pagination or result size limits, which matter for a list 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 tight sentences that front-load the resource and field list, with the include_inactive hint following. The trailing 'GraphQL: products' fragment is compact and maps the tool to its underlying query, though it reads as slightly cryptic without context.

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 compensates by enumerating the returned fields, and the annotation covers the read-only safety profile, so an agent has enough to invoke it correctly. The remaining gap is pagination/result-size behavior, which the schema's after/first parameters imply but the description never connects.

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 all four parameters (after, first, query, include_inactive) are already documented in the schema, establishing a baseline of 3. The description only restates include_inactive and adds the 'cents' unit for price/cost, which is minor added value rather than compensating detail.

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 (List) and resource (retail products) and enumerates the returned fields (brand, SKU, barcode, price, cost, category), so an agent can tell it apart from boulevard_list_services or boulevard_list_orders without opening the schema. It does not explicitly name a sibling it is not, but the resource noun 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?

The only conditional guidance is 'Set include_inactive to include retired products,' which describes a parameter rather than when to choose this tool over an alternative. There is no statement of when-not to use it or which sibling handles related resources (e.g., services, orders).

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 assert readOnlyHint=true, so the safety profile is covered. The description adds the returned field set, which helps, but says nothing about pagination behavior or result ordering; the cursor/paging contract lives only in the schema. Adequate, not rich.

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 enumerating the payload, plus a short GraphQL anchor. Nothing is padded or redundant.

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 usefully compensates by listing the returned attributes and their units, which an agent needs to interpret results. Pagination is left to the schema, which is reasonable given the full coverage there.

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 both parameters (after, first) are fully documented there with defaults and cursor semantics. The description adds no parameter meaning beyond that, 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 (list) and resource (the service menu) and enumerates the returned fields: name, category, default duration in minutes, default price in cents, and add-on flag. No sibling tool lists services, so the resource alone differentiates it cleanly. The GraphQL mapping ('services') adds a precise anchor.

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 (fetch the service catalog) but never states when to reach for this versus other list tools, nor any prerequisites or exclusions. For a plain catalogue read, that gap is tolerable, but no explicit routing guidance 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 readOnlyHint=true annotation already establishes the safe read profile, lowering the burden. The description does add value by naming what the shift records expose (clock-in/out times, weekday, availability, recurrence), but it says nothing about pagination, result limits, or whether staff_ids narrows the result set.

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 covers the verb, scope, and returned fields, followed by a terse GraphQL mapping hint. Nothing is padded or redundant.

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

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

For a read-only list tool with no output schema, full schema coverage, and safety annotations, the description conveys enough to call it correctly. The omissions (staff_ids filter behavior, pagination) are minor for a tool whose parameters are fully documented in the schema.

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 all four parameters including the location_id URN format and date patterns. The description only gestures at the date range and single location, adding no syntax or meaning beyond the schema; the staff_ids filter is entirely absent from the prose.

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 (List) and resource (staff working shifts) with the scope of one location and a date range, plus what the records contain. It is clear on its own, though it does not explicitly differentiate itself from the adjacent boulevard_list_staff or boulevard_list_timeblocks siblings, which an agent could plausibly confuse with shifts.

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 data domain (one location, date range) but never states when to use this tool versus alternatives such as boulevard_list_timeblocks or boulevard_list_staff, nor any exclusions or prerequisites. There is no explicit usage routing at all.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the description carries a lighter burden. It adds some value by disclosing what the response contains (role, locations, contact details, bookable status), but says nothing about pagination defaults or rate/scale behavior beyond what the schema already covers.

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 that leads with the verb and resource, then the returned fields, then the filter clause. The trailing 'GraphQL: staff' is implementation context that may help mapping but is slightly extraneous.

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, naming the fields returned is genuinely useful and covers the main gap. Combined with 100% schema coverage for parameters and the readOnly annotation, the definition 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%, so all three parameters (after, first, query) are fully documented in the schema itself. The description's mention of 'optionally filtered by a query' adds no syntax or semantic detail beyond that, so the 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?

States a specific verb+resource ('List staff members') and enumerates the returned attributes (role, locations, contact details, bookable-online status). It is clearly distinct from the other list_* siblings (clients, appointments, services), though it does not explicitly contrast with them.

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 only usage hint is 'optionally filtered by a query,' which restates the schema's query parameter rather than giving when/when-not guidance. There is no mention of pagination context, prerequisites, or when another tool would be preferable.

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

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

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered by structured data. The description adds useful context that the returned ids feed boulevard_add_tag, but says nothing about pagination traversal or ordering beyond what the schema already documents.

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 with zero filler; the tool's purpose and its downstream use are front-loaded. The terse GraphQL note adds a minor mapping hint without bloating the text.

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

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

For a simple two-parameter list tool with full schema coverage and a readOnly annotation, the definition covers purpose and downstream usage adequately. Pagination is handled by the schema, so nothing essential is missing, though return ordering is unstated.

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 'after' cursor and 'first' page-size parameters are fully documented in the schema. The description adds no parameter detail, which is the correct baseline when the schema carries the load.

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 ('List the tags') and narrows scope to tags 'defined for the business'. The parenthetical pointing to boulevard_add_tag separates it from the sibling that mutates tags, 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 a clear use case - fetch ids needed as input to boulevard_add_tag - which tells the agent when this tool is the right first step. No explicit exclusions or competing alternatives are named beyond that, but the workflow context is unambiguous.

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

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

Annotations already declare readOnlyHint=true so safety is known. Beyond that, the description adds the GraphQL field name (timeblocks) but nothing about pagination behavior, filtering constraints, or what is returned. With annotations covering the read-only profile, the description should still disclose key behaviors for a paginated list tool but does not.

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 stating the resource, scope, and meaning, with a short GraphQL mapping note. Every element is front-loaded and no filler is present.

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

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

For a read-only paginated list tool with no output schema and full schema coverage, the description covers the essentials but omits return-shape guidance, pagination behavior, and when/how to use the query filter beyond what the schema states. Adequate but with clear gaps.

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 schema already documents all four parameters including the query filter syntax and cursor semantics. The description adds only the GraphQL field name 'timeblocks' and does not deepen parameter meaning beyond what the schema says. 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 (List) and resource (blocked time / timeblocks), and clarifies the scope as staff calendars at one location, with examples of what timeblocks represent. It does not explicitly contrast with sibling boulevard_create_timeblock or boulevard_list_shifts, but the resource name is distinct and unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no mention of related tools like boulevard_create_timeblock for writing timeblocks. The description states what it does but gives no routing context for an agent choosing among the many list_* siblings.

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 declare destructiveHint=true, and the description justifies it by disclosing that notes are replaced rather than appended and that only four states are reachable. It stops short of permissions/auth requirements or irreversibility details, but adds meaningful context beyond the annotation.

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 tightly packed sentences: capability first, boundary second, with the GraphQL mutation name as a compact trailing detail. No filler or redundant 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?

For a 3-parameter mutation with no output schema, the description covers what changes, which values are valid, and what is out of scope, which is enough to call it correctly. Minor gaps (no mention of permitted states beyond the enum, no side-effect or return-shape note) keep it from a 5.

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 interpretation the schema lacks, mapping the enum values to real-world intents (CONFIRMED = confirm, ARRIVED/ACTIVE = check the client in). It also reinforces that notes is a full replacement.

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 (update/replace), resource (appointment), the exact fields affected (internal notes and state), and enumerates the target states. It also draws a hard boundary ('Does not cancel or reschedule'), so an agent can distinguish this from other appointment operations 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?

Gives concrete usage context with examples ('confirm, or check the client in') and a clear exclusion for cancel/reschedule. It does not name a sibling alternative, but no cancel/reschedule sibling exists in the sibling list, so the negative guidance is about capability scope rather than tool routing.

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

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

Annotations only declare destructiveHint=true, so the description earns real credit for clarifying 'Only the fields you pass change' — this tells the agent the mutation is a partial update and that unmentioned fields are not wiped, directly tempering the destructive hint. It still omits how to clear a field, auth/permission requirements, and error or conflict behavior, so it is not fully 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?

Two tight sentences with zero filler; the mutation scope is front-loaded and the partial-update semantics and GraphQL mapping follow compactly. 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?

For a mutation tool with no output schema, the definition covers the mutable surface and partial-update semantics well, which is most of what an agent needs. Remaining gaps are secondary: no guidance on nulling out fields despite destructiveHint, and no mention of permission requirements or failure modes.

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 all eight parameters (including the required client_id and formats like E.164 phone and YYYY-MM-DD dob) are already documented in the schema. The description merely restates the mutable field list in prose without adding format, constraint, or edge-case meaning, 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?

Names a specific verb+resource ('Change a client') and enumerates exactly which attributes are mutable (name, email, mobile phone, DOB, pronoun, external id), plus the GraphQL mutation it maps to. This is unambiguously distinct from sibling tools like boulevard_create_client or boulevard_get_client.

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 mutation to use when altering an existing client, but the description names no alternatives, no prerequisites, and no when-not-to-use condition. The partial-update note hints at usage but is really behavioral, not routing guidance.

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