Boulevard MCP by usefulapi

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

The annotation already declares destructiveHint=true, so the agent knows this mutates state. The description adds useful context that the tag must pre-exist and which entity types are taggable, but says nothing about what the mutation destroys, whether it is reversible, or how to undo it. Given annotation coverage, this is adequate but 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?

Two short sentences with zero filler, front-loading the action and the source of the tag id. The trailing GraphQL mapping is a compact developer aid that does not bloat 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 two-parameter mutation with no output schema and fully documented parameters, the description covers purpose, source of the tag id, and target record types. The main remaining gap is the absence of any note on reversibility or effect on existing tags, which is minor given the destructiveHint annotation.

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 entity_id and tag_id formats are already documented in the schema, making 3 the baseline. The description only adds the extra hint that entity_id may be a client or appointment, without adding syntax or constraint detail beyond the schema.

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

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

States a specific verb (apply) and resource (tag) plus the target (a taggable record such as a client or appointment), and names boulevard_list_tags as the source of valid tag ids. An agent can distinguish this write from the read-oriented list_tags sibling without opening any schema.

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

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

Gives a clear prerequisite (the tag must already exist and come from boulevard_list_tags) and identifies the kinds of records it applies to, so the agent knows the preconditions for calling it. It stops short of stating when not to use it (e.g., creating a new tag, or removing one), so no explicit exclusions.

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

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

Annotations already carry destructiveHint=true, so the safety profile is partly covered. The description adds the duplicate-avoidance workflow but says nothing about required vs optional fields, auth/permission needs, error behavior on duplicate creation, or what the call returns.

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 the action front-loaded, then the workflow tip, then the backend mapping. Nothing is redundant or padded.

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 7 parameters that are all optional and no output schema, the description omits important context: whether any field is effectively required to create a usable client, and what a successful call returns (e.g. the new client id). It covers the dedup workflow but not the full call 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%, so the schema already documents all 7 fields with formats and patterns. The description only references email/phone in the context of dedup checking, adding no syntax or constraint detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a new client profile') and even names the underlying GraphQL mutation (createClient). It is easily distinguishable from siblings like boulevard_create_client_note and boulevard_update_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?

Gives an explicit precondition and a named alternative: 'Check boulevard_list_clients by email or phone first to avoid a duplicate.' That is real when-to-use routing, though it never says when to prefer boulevard_update_client instead or what happens if the check is skipped.

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; the description usefully adds that the note is staff-visible (not customer-facing) and gives content examples. It does not address permissions, whether the note is editable/deletable afterward, or why the operation carries a destructive hint, leaving a real gap 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?

One tight sentence with the resource and visibility constraint front-loaded, followed by a brief GraphQL mapping. Nothing is redundant, though the GraphQL name is of marginal use to an agent.

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 only a destructiveHint annotation, the description covers the essentials of what it does but omits behavioral details such as required permissions, effect on the existing profile, and any confirmation of success.

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 client_id and text are already documented with format details. The examples ('formulas, preferences, allergies') clarify what sort of content belongs in text, adding modest value beyond the schema.

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

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

States a specific verb ('add') and resource ('internal note to a client's profile'), which clearly separates it from sibling readers like get_client or list_clients. It does not explicitly contrast with the other writers (update_client, add_tag), but the purpose 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 parenthetical 'visible to staff' implies the note is internal rather than client-facing, which hints at when to use it. However, there is no guidance on when to prefer this over update_client or add_tag, and no 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?

Annotations only supply destructiveHint=true, and the description adds real semantic context: the block consumes availability so it cannot be booked. It does not state permission requirements, what happens to any existing appointment in that window, or whether the block can later be removed or edited. The 'prevents booking' framing and the destructive hint are broadly consistent rather than contradictory.

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 tight sentences, front-loaded with the operation and its effect; the 'One-off only' constraint and the GraphQL mapping name both earn their 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?

For a 6-parameter mutation with no output schema, the description covers what is created, its effect, and its one-off limitation. It omits return information (the created timeblock identifier) and failure/permission context, which is a minor gap rather than a blocker.

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, start_time, location_id) is already documented in the schema. The description only loosely maps to staff/location and adds no format or constraint detail beyond it, 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+resource+scope: blocking time on one staff member's calendar at a location, and clarifies the effect ('so it cannot be booked'). This is clearly distinguishable from read-side siblings like boulevard_list_timeblocks.

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' constrains the use case (no recurring blocks) and the parenthetical names example reasons (break, meeting, personal time), implying intent. However, it never names alternatives or when-not-to-use cases, e.g. how to view existing blocks or how this differs from shift management.

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 the safety profile, yet the description goes further and discloses the returned surface — time, state, notes, client, services with staff and price (in cents), cancellation details, tags. The 'price (in cents)' unit and the field inventory are genuine additions that compensate for the absent output schema. It does not cover not-found/error behavior, which keeps 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?

One front-loaded sentence covering operation, identifier and return shape, with no filler. The trailing 'GraphQL: appointment.' is terse and slightly cryptic but still earns its place as a backend-type mapping.

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, single-parameter lookup with no output schema, the description supplies the return-field inventory that the structured fields omit. Nothing essential to calling it correctly is missing, though error/not-found handling 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% and the single appointment_id is already documented with a urn:blvd:Appointment:<uuid> example. The description adds only 'by id', so the schema does the heavy lifting and 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 contrasts implicitly with the list siblings via 'one ... by id'. It also enumerates exactly what each record contains, so an agent knows both the operation and its payload.

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?

'Fetch one appointment by id' implies the keyed-lookup use case, but it never names an alternative sibling (e.g. boulevard_list_appointments for browsing/filtering) or states when not to use it. 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context — that it is cheap and returns the credential-scoped business — but discloses nothing more about rate limits, auth failure behavior, or error cases.

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 clauses plus a GraphQL mapping; front-loaded with the verb and resource, with no filler. Every phrase 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 compensates by enumerating the returned fields and clarifying the credential-scoped nature of the resource. Nothing an agent needs in order to call a zero-parameter read tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly frames the resource as the business the credentials act for, which is the only 'input' semantics that matters 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 (Fetch) and resource (the Boulevard business the credentials act for), then enumerates the returned fields (name, timezone, address, phone, website). It is clearly distinguishable from siblings like boulevard_list_locations 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?

"A cheap way to confirm the setup works" gives a concrete when-to-use scenario (credential/setup verification). It does not name alternatives or state exclusions, but the intended 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 only declare readOnlyHint=true, so the description carries the return-value burden and does so by enumerating the payload (contact details, appointment count, balance in cents, scheduling alert, tags, notes). It omits error behavior for non-existent ids and any permission requirements, which keeps it below 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 tight sentence that leads with the verb and scope, then lists the return payload with no filler. Every clause earns 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?

There is no output schema, and the description compensates by enumerating the fields returned, so an agent knows what to expect. It lacks only edge-case behavior (missing/invalid id) and auth notes, which are minor for a simple read.

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 100% schema description coverage on a single required parameter, the schema already documents 'client_id' including the urn:blvd:Client:<uuid> format. The description's 'by id' adds no syntax or format detail beyond it, 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 client') with singular scope plus the identifying key ('by id'), which implicitly separates it from the plural boulevard_list_clients. It does not name that sibling explicitly, so it falls short of the top tier.

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 tool is clearly meant for retrieving a single known client id, but there is no statement of when to prefer it over boulevard_list_clients or boulevard_get_appointment, and no preconditions or exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the returned payload includes totals and line items, and amounts are denominated in cents – a convention an agent could not infer from the schema or annotations. It stops short of noting error/not-found behavior.

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 carries the verb, resource, key input, and return contents, with the trailing 'GraphQL: order' note kept to a minimum. 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?

For a simple single-record read with annotations covering safety, the definition covers input, return contents, and amount units. With no output schema present, slightly more detail on the returned fields or missing-order behavior would make it fully self-sufficient.

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

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

Only one parameter and schema description coverage is 100%; the schema already documents order_id including the urn:blvd:Order:<uuid> format. The description's 'by id' adds essentially nothing beyond the schema, 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 (fetch) and resource (one order by id) and immediately scopes it to a single record, which cleanly separates it from the sibling boulevard_list_orders. The parenthetical enumeration of what an order contains (services, products, gratuity, gift cards) further pins down the resource.

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 'by id' – call it when you already hold an order identifier – but the description never states when to prefer this over boulevard_list_orders or what to do without an id. No alternatives, prerequisites, or exclusions are named.

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 establishes the safety profile, so the description's added value is the disclosure of the returned payload ('client, services, staff, state and cancellation'), which matters because there is no output schema. It stops short of describing pagination behavior or result ordering.

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 scope statement is front-loaded in the first sentence and the return-payload list is compact. The trailing 'GraphQL: appointments.' mapping is a small but legitimate addition; overall there is 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 read-only list tool with a fully documented 5-parameter schema and no output schema, the description covers scope, optional filters, and the shape of each returned appointment. Missing only minor operational details like pagination semantics, which the schema partially covers via 'after'/'first'.

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%, including a detailed QueryString grammar for 'query' and format notes for client_id and location_id, so the schema already carries the parameter burden. The description only restates the high-level filtering intent (client, date range, staff member) without adding syntax or constraints beyond the schema, matching the baseline.

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

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

The description gives a specific verb and resource ('List appointments') plus its scope: one location, optionally one client, filterable by query. This implicitly separates it from the singular sibling boulevard_get_appointment, but it never names or contrasts with that sibling explicitly, so it falls short of the top mark.

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 conveys the common narrowing axes ('optionally for one client and filtered by a query such as a date range or staff member'), which implies when the filters are useful. However, it gives no explicit when-to-use/when-not guidance and no routing to alternatives such as boulevard_get_appointment for a single appointment.

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, non-mutating read. The description adds only the trivial GraphQL mapping ('clients') and no behavioral traits such as pagination limits, result caps, or ordering, so it adds little beyond the structured fields.

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

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

One tightly written sentence that front-loads the primary action (list) and then enumerates the alternative lookup modes. No filler, no 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 zero-required-parameter list tool with a fully documented schema and a readOnly annotation, the description is nearly sufficient. Since there is no output schema, it could say a bit more about what a page of results contains, but the pagination contract is already in the parameter docs.

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, emails, client_ids) are already documented in detail. The description's inline example ('name = 'Jane Doe'', mobilePhone = ...) is a lighter restatement of what the schema's query description already covers, so the baseline 3 is right.

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 clients') plus the three search modes (email, id list, query). An agent can distinguish this from the singular boulevard_get_client by the plural 'list/search' framing, though the sibling is never 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?

Gives clear conditions for each mode: list everything, or filter by emails, client_ids, or a filter expression. It does not explicitly say when to prefer this over boulevard_get_client or boulevard_list_appointments, but the retrieval context is well implied for a read-only list 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the dependency context (other tools consume these location ids), which is genuinely useful, but says nothing about pagination behavior or result ordering 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?

Three short clauses, zero filler, and the resource scope is front-loaded ahead of the dependency note and the GraphQL mapping.

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 helpfully enumerates the returned fields (id, name, timezone, address) and notes the GraphQL root, while pagination is fully handled by the schema. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, with both cursor params fully documented in the schema, so the baseline of 3 applies. The description adds no parameter syntax or default detail beyond the schema.

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

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

States a specific verb and resource ('List the business's locations') and even enumerates the returned fields (id, name, timezone, address), which clearly separates it from the many other boulevard_list_* siblings by resource type.

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?

'Most other tools need a location id from here' gives a concrete reason to call this tool first, effectively routing the agent in dependency terms. It stops short of naming a specific alternative or exclusion, but the usage 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining job is small. It adds the returned field set and the GraphQL field mapping ('memberships'), but says nothing about ordering, result limits, or how pagination terminates.

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 tight sentence, front-loaded with verb and resource, with the field list packed economically after a dash. The trailing 'GraphQL: memberships' is mildly internal but earns its place as a backend mapping hint.

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 enumerates returned fields (status enum values, price in cents, interval, term, next charge date), which is exactly what's needed. Only pagination behavior and any ordering guarantees 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 both pagination parameters (after, first) are fully documented in the schema and the description need not repeat them. It adds no parameter-level meaning beyond that, which is the expected baseline 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 ('List') and resource ('client memberships sold by the business') and enumerates the returned fields, so the agent knows exactly what it gets back. It does not explicitly differentiate itself from sibling list tools (list_clients, list_orders, list_products), though the resource is unique among 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 description gives scope ('sold by the business') but no when-to-use guidance, no exclusions, and no named alternative. It never mentions that results are paginated or how to page further, which is the one usage decision an agent must make here.

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 real context — amounts are in cents and results are scoped to one location — but it never says what an unfiltered call returns (open vs closed orders), whether results are paged, or any rate/limit behavior.

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?

One dense sentence front-loads the verb, scope and returned fields, followed by a short GraphQL pointer. The parenthetical totals list is long but earns its place; the trailing 'GraphQL: orders.' fragment is terse but harmless.

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 naming the returned monetary fields and their unit, and pagination is covered by the schema's after/first definitions. It falls short only on default result scope and pagination behavior, which an agent may need when forming the first call.

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 schema's query parameter is documented far more thoroughly (field list, syntax, examples) than the description's brief 'closedAt range or clientId' mention. Baseline 3 is appropriate since the schema already carries the semantics.

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 (checkout orders) plus the scope constraint 'at one location', which cleanly separates it from the sibling boulevard_get_order for a single order. It also enumerates the monetary fields returned, so an agent knows what it gets 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?

Only 'optionally filtered e.g. by closedAt range or clientId' implies when the query parameter is useful; there is no when-to-use versus boulevard_list_appointments/boulevard_get_order guidance and no note on what unfiltered results contain. Usage is inferable but not 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?

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description does add value beyond the annotations: default filtering out of inactive/retired products, cost expressed in cents, and the underlying GraphQL query name for debugging. It does not discuss pagination behavior or result limits, but those are covered by the 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?

Two compact sentences; the resource and field list lead, and the include_inactive behavior follows immediately. No filler or restatement of the title.

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

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

With no output schema, the description usefully enumerates the returned fields, and pagination/filter syntax live in the schema descriptions. Safety is handled by annotations. Minor gap: no note on result limits or ordering, but the agent has enough to invoke 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 four parameters (after, first, query, include_inactive) are already documented with format and range details. The description only echoes include_inactive and adds the 'cents' unit note, which maps to returned data rather than parameters. Baseline 3 is appropriate.

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

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

Names a specific verb and resource ('List retail products') and enumerates the returned fields (brand, SKU, barcode, unit price, cost, category), plus maps to the underlying GraphQL root ('products'). No sibling tool covers products, so 'list_products' is unambiguously distinguishable from list_clients/list_orders/list_services.

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 guidance is 'Set include_inactive to include retired products', which explains default exclusion behavior for one parameter. There is no statement of when to reach for this tool versus other list tools, nor any prerequisite or context guidance. Usage is implied by the resource name rather than stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered and the bar is lower. The description adds real value by disclosing the return payload's field semantics and units (minutes for duration, cents for price), which an agent cannot get from an absent output schema. It does not state pagination behavior, though the schema handles that.

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?

One sentence, front-loaded with the verb and resource, with the returned fields packed in without filler. The trailing "GraphQL: services" is terse and aids API mapping rather than padding.

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

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

For a no-required-param list tool with full parameter documentation and a read-only annotation, the description covers purpose and return shape. Only minor gaps remain (no mention that results are paginated or any scoping limits), and the schema already documents pagination.

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 both parameters (after cursor, first page size with documented 1-100 range and default). The description adds nothing about the parameters, so the baseline 3 applies since the schema does all the work.

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

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

States a specific verb (List) and resource (the service menu) and enumerates exactly what each row carries: name, category, default duration in minutes, default price in cents, and add-on flag. No sibling tool covers services, so the resource alone distinguishes it from boulevard_list_products, boulevard_list_staff, etc.

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 use case is implied by the content it returns (a bookable service menu with durations and prices), but there is no explicit when-to-use statement, no when-not-to-use, and no named alternative. Adequate but leaves the agent to infer context.

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 establishes this is a safe read, so the description only needs to add context — and it does, by disclosing what the result contains (clock-in/out times, weekday, availability, recurrence) and the underlying GraphQL entity. It omits pagination/size limits and default behavior when staff_ids is omitted.

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?

One sentence, front-loaded with the verb/resource/scope before the returned-field list, with zero filler. 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?

With no output schema, the description usefully enumerates what is returned, and the schema fully documents inputs. Slight gap: no mention of pagination, result limits, or default staff filtering for a list endpoint over a date range.

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% (4 params, all documented, including format and location id example), so the schema carries parameter meaning. The description reinforces the date-range and single-location concepts but adds no syntax or behavior beyond the schema; 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 (staff working shifts) with scope (one location, date range) and enumerates the returned concepts (clock-in/out, weekday, availability, recurrence). The 'shifts' resource is distinguishable from the sibling boulevard_list_staff roster tool, and the GraphQL field mapping ('shifts') adds precision.

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 scope phrasing ('at one location for a date range') implies when the tool is applicable, but there is no explicit when-to-use/when-not or naming of an alternative (e.g., list_staff for a staff roster vs shifts for schedules). Usage must be inferred.

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, so the description is not carrying the full safety burden. It adds useful context about what is returned (role, locations, contact details, online-bookable status), but says nothing about pagination behavior or result volume, which the schema alone 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?

One front-loaded sentence naming the resource and its returned fields, plus a short GraphQL hint. No filler, nothing repeated unnecessarily.

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 enumerates the fields returned, compensating for the missing return-value documentation. Pagination is handled by the schema and safety by annotations, so only minor gaps remain.

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 already fully documented, including the QueryString filter syntax and examples. The description only restates that a query filter is optional, adding no meaning beyond the schema; 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 ('List staff members') and enumerates the returned fields (role, locations, contact details, bookable-online flag), so an agent knows exactly what it gets. It also names the underlying GraphQL root field ('staff'), which disambiguates it from the many other list_* siblings by resource.

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 'optionally filtered by a query' implies the query parameter is optional filtering, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safe read profile is covered. The description adds the mapping to boulevard_add_tag's expected ids and the underlying GraphQL field name, but says nothing about pagination or result ordering beyond what the schema already gives.

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 tight sentence with the purpose front-loaded, plus a short GraphQL field mapping. Every element earns its place, though the trailing 'GraphQL: tags' fragment is terse enough to be slightly opaque.

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, zero-required-param list tool with full schema coverage and annotation-declared safety, the definition supplies the purpose and the relationship to boulevard_add_tag. Nothing critical is missing, though return shape is undocumented (no output 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%, with both 'after' and 'first' fully documented including cursor source and page-size range. The description adds no parameter detail, 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 (tags) scoped to the business, and distinguishes itself from the sibling boulevard_add_tag by referencing the ids for that tool. An agent can identify the right 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?

Implies the use case clearly: fetch tag ids to feed into boulevard_add_tag. It names the related sibling and the reason to call this one, but offers no explicit when-not-to-use or pagination guidance. Clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds the GraphQL field name (timeblocks) and the per-location scoping ("at one location"), which is useful context, but it says nothing about result volume, ordering, or cancellation filtering behavior.

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 scope; the parenthetical examples of timeblock types earn their place by clarifying the resource. Zero 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 read-only list tool with no output schema and full schema-level parameter documentation, the description covers purpose, scope, and data domain adequately. Pagination and return shape are handled in the schema, so nothing essential is missing, though a hint about filtering by staff or date range would round it out.

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 four parameters (after, first, query, location_id) are already fully documented in the schema, including the QueryString syntax and cursor semantics. The description's "at one location" only loosely reinforces location_id and adds nothing beyond the schema, 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?

Specific verb+resource ("List blocked time on staff calendars") with the scope narrowed to one location, and it disambiguates the domain by enumerating what a timeblock is (breaks, meetings, personal time). It does not explicitly reference the sibling boulevard_create_timeblock, but the List/Create verb split is self-evident.

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: an agent can infer this is the read path for blocked time at a location, and the required location_id is evident from the schema. There is no stated when-to-use, when-not, or routing to alternatives such as boulevard_list_shifts or boulevard_get_appointment.

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 carry only destructiveHint=true, so the description is the main source of behavioral context. It usefully discloses that notes are replaced (existing notes lost) and that cancellation/rescheduling is out of scope, but says nothing about required permissions, reversibility of state transitions, or side effects like notifications to the client.

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, both front-loaded with the actionable content: capability first, exclusion second. Every clause earns its place, with 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 simple three-parameter mutation with no output schema, the description covers what can be changed and what cannot, which is the bulk of what an agent needs. It stops short of noting authorization requirements or transition rules, but no structured field is available to carry that.

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 enum is fully documented in the schema, so the schema already does the heavy lifting for all three parameters. The description restates the state values and the replacement semantics of notes, adding confirmation but no new syntax or format 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?

The description names a specific verb and resource (replace notes / move state on an appointment) and lists the exact target states, plus the underlying GraphQL mutation updateAppointment. It scopes itself by stating it does not cancel or reschedule, though it never names a sibling tool, so differentiation is inferred rather than explicit.

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

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

Usage context is concrete: the parenthetical 'e.g. confirm, or check the client in' maps states to real workflows, and 'Does not cancel or reschedule' states an explicit non-use case. There is no named alternative tool to route to, 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 supply destructiveHint=true, and the description adds the useful patch semantic that unspecified fields remain untouched — a real behavioral detail beyond the annotation. It stops short of permission requirements, behavior on invalid or missing clients, and whether changes are reversible or logged.

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 patch-behavior constraint is front-loaded and the GraphQL mapping is appended as a compact reference. Every clause earns 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?

For a mutation tool with no output schema, the description covers scope and field semantics but says nothing about what the call returns or how failures surface, and it omits auth/permission context. It is adequate against a fully documented schema 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 100%, so every parameter (client_id, dob, email, pronoun, names, external_id, mobile_phone) is already documented with format and examples in the schema. The description restates the field list without adding formats, constraints, or required-vs-optional context beyond what the schema provides.

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 ('Change') plus the resource (a client) and enumerates the mutable fields, so an agent immediately knows what this does. It implicitly differentiates from boulevard_create_client and boulevard_get_client via the enumeration and patch semantics, but never names a 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?

'Only the fields you pass change' gives partial-update guidance and implies this is the tool to use for modifying an existing client rather than creating one. However, there is no explicit when-to-use/when-not guidance and no mention of prerequisites such as needing a valid client_id or read-back alternatives.

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