Shop Boss MCP by usefulapi

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so restating 'Read-only' earns no credit. The added value is limited to the permission caveat that results depend on the API key's resource permissions, which is genuinely useful context but doesn't cover 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?

Three short sentences with the resource scope front-loaded and no filler. The telegraphic style ('scheduled dates, customer and vehicle references') is slightly fragmentary but wastes nothing.

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 nine optional parameters, no output schema and low schema coverage, the description should explain at least the filtering and pagination model. It gives only a date format convention and an auth note, leaving an agent guessing about how status/name/appointmentId filters interact and what page/pageSize defaults do.

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

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

Schema description coverage is only 11% (just shopId), so the description must compensate for eight undocumented parameters. It only adds the date format rule for startDate/endDate; filtering semantics for status, firstName, lastName, appointmentId, page and pageSize are left entirely unexplained.

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

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

The description names the resource (appointments) and the fields surfaced (scheduled dates, customer and vehicle references), so an agent can infer it is a list/read operation on appointments. However, the verb is the soft 'Review' rather than an explicit list/query statement, and it never distinguishes this tool from the many sibling list_* tools beyond its name.

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

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

There is no guidance on when to use this tool versus alternatives such as shopboss_list_customers or shopboss_list_repair_orders, nor any mention of which filters are worth combining. The only contextual sentence concerns API key permissions, which is authorization context rather than usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so repeating 'Read-only' adds nothing. The genuinely new information is the permission caveat ('Resource permissions depend on your Shop Boss API key'), which warns the agent results may be scoped by key. It says nothing about pagination behaviour or whether 'available' is a filter, which is the main behavioral unknown.

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, purpose front-loaded, no padding. The only waste is restating 'Read-only', which annotations already cover.

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 read-only list tool with no output schema, the essentials are present, but with two of three parameters undocumented in both schema and description and no mention of pagination limits or the shape of a bay entry, an agent cannot confidently page or interpret results without trial and error.

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

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

Schema description coverage is only 33% — shopId is documented in the schema, but page and pageSize carry only defaults and min/max with no semantics. The description does not compensate at all: it never mentions paging, defaults, or the shopId scoping parameter, so an agent must guess how to page through a large bay list.

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 service bays') and adds a purpose ('for appointment planning') that separates it from the other shopboss_list_* siblings. The word 'available' is slightly ambiguous — it's unclear whether it means bays defined in the shop or bays currently unoccupied — but the resource is still 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 phrase 'for appointment planning' implies the context in which to reach for this tool, but there is no explicit when-not guidance and no named alternative (e.g., use shopboss_list_appointments for existing bookings). The agent has to infer that this is the lookup step before booking.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful permission context about the API key, but it largely repeats 'Read-only' and does not explain pagination or result 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?

The description is three short, front-loaded sentences with no wasted text. It communicates the core lookup purpose and permission caveat efficiently.

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 list tool with five optional parameters and no output schema, the description is too sparse. It omits filtering, pagination behavior, and return-value context that an agent would need to invoke it effectively.

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 description provides no meaning for the five parameters, including page, pageSize, jobName, cannedJobId, or shopId. With schema description coverage at only 20%, the description should compensate but does not.

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

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

The description states a specific lookup action and resource concept: predefined automotive services with pricing context. It is clear enough to understand the operation, but it does not explicitly distinguish this tool from other list endpoints such as parts or repair 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?

There is no explicit guidance on when to use this tool versus related list tools, nor are there conditions or exclusions. The only contextual note is that resource permissions depend on the API key.

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, idempotentHint and openWorldHint, so "Read-only" earns no credit and the bar is lower. The one genuinely additive statement is that resource permissions depend on the caller's API key, which tells the agent authorization may be scoped. Nothing is said about pagination, total counts, or result ordering for what is an open-world list.

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 with no filler; the purpose lands first and the constraints follow. It is efficient, though the terseness contributes to the gaps elsewhere rather than being a model of density.

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

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

There is no output schema, so the description could reasonably say what a category record contains or that results are paged, and it does neither. For a simple zero-required-parameter read-only list this is adequate, but the paging contract is left entirely to the schema's defaults and bounds.

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

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

Schema coverage is only 33% — shopId is documented in the schema while page and pageSize carry bounds and defaults but no descriptions. The description does not compensate at all: it never mentions paging, defaults, or how the three parameters interact, leaving the agent to infer pagination semantics from parameter names alone.

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

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

States a specific verb and resource ("Look up the shop's repair complaint categories"), which distinguishes it cleanly from the sibling list_* tools covering appointments, customers, vehicles, etc. It does not explicitly name a sibling or contrast, but the resource noun makes the distinction unambiguous.

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

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

Usage is implied by the list-style name and the read-only statement, but there is no explicit when-to-use guidance, no note on when to paginate through all results, and no contrast with any sibling tool. The API-key permission sentence is contextual but not a selection guideline.

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, idempotentHint, and openWorldHint, so "Read-only" repeats structured data. The one real addition is "Resource permissions depend on your Shop Boss API key," which tells the agent failures may be authorization-related. It omits pagination behavior (page/pageSize), result ordering, and whether filters combine with AND logic.

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

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

Two front-loaded sentences with no filler; the lookup keys come first. The second sentence's "Read-only" clause is slightly wasteful since annotations already cover it.

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

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

For an 8-parameter listing tool with no output schema and near-zero schema coverage, this is under-specified: pagination limits (default 25, max 100), filter combination rules, and what "contact and account context" actually contains are all absent. An agent can call it, but may do so with wrong page expectations or stacked filters.

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

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

Schema description coverage is only 13% — shopId is the sole documented parameter out of 8. The description partly compensates by naming ID, name, email, and phone as lookup keys, but leaves firstName vs lastName vs partial matching, and page/pageSize entirely unaddressed, so the agent gets no help on the undocumented half.

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?

"Find customers by ID, name, email or phone" names a specific verb, resource, and lookup keys, which cleanly separates it from siblings like shopboss_list_vehicles or shopboss_list_repair_orders. It stops short of 5 because it never clarifies whether calling with no filters returns a full customer list or requires at least one criterion.

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 no when-to-use guidance, no prerequisite context beyond a vague permission note, and never routes the agent to an alternative (e.g., a vehicle or repair-order lookup when starting from a customer). An agent must infer usage purely from the tool name.

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

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

The description adds useful behavioral context beyond annotations: payroll, home addresses, and emergency contacts are omitted, and access depends on the Shop Boss API key. It confirms the read-only nature already declared by annotations without contradicting them, though it does not cover pagination or response shape.

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

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

The description is three short, front-loaded sentences with no wasted prose. The return fields, omitted data, read-only behavior, and permission caveat each add distinct value.

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, the description usefully states which employee fields are returned and which sensitive fields are omitted. However, it does not explain the six input parameters, especially pagination and name/ID filters, which leaves a meaningful gap for correct invocation.

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

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

Schema description coverage is only 17%, with six parameters and only shopId documented in the schema. The description does not explain page, pageSize, firstName, lastName, or employeeId, so it does not compensate for the low schema coverage.

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: looking up employee names, job descriptions, mechanic numbers, and active status. It clearly distinguishes this from sibling list tools by naming employee-specific fields, though it does not explicitly frame the operation as a paginated directory listing.

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 purpose and by the note that it is read-only, but there is no explicit guidance on when to use this versus related queries. No alternatives are named, and filtering behavior for firstName, lastName, or employeeId is not discussed.

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, idempotentHint and openWorldHint, and 'Read-only' merely restates them. The one piece of added context is that resource visibility depends on the API key, which is genuinely useful, but nothing is said about pagination behavior, default page size, or whether filters combine.

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 the core purpose front-loaded and zero filler. It is efficient, though the space saved is spent nowhere useful given the missing filter guidance.

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?

A seven-parameter, zero-required listing tool with no output schema and almost no schema descriptions needs the description to explain the filter set and pagination defaults. The description covers neither, so an agent cannot tell whether results are paginated, how to narrow to one repair order, or what shape the parts records take.

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

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

Schema description coverage is only 14% (just shopId), so the description must compensate for six undocumented parameters. It mentions none of partId, partNumber, description, repairOrderId, page or pageSize, leaving the agent to guess what each filter does and how paging works.

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+resource ('Review parts, quantities, prices and ordering context') and its repair-order scope, which hints at the distinction from shopboss_list_parts and shopboss_list_part_sales. It never explicitly names those siblings, so the differentiation is inferable rather than stated.

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

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

There is no guidance on when to use this versus shopboss_list_parts, shopboss_list_repair_orders, or shopboss_list_part_sales, and no note that all seven parameters are optional filters. The only usage-adjacent sentence is a permissions caveat, which constrains access rather than selection.

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 and idempotentHint, so 'Read-only' adds nothing. The permission note tied to the Shop Boss API key is genuine behavioral context beyond annotations, but pagination behavior and default page size are never mentioned despite page/pageSize parameters existing.

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 purpose front-loaded and no filler. The efficiency comes at the cost of under-specification rather than padding, which is the better failure mode.

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?

Seven optional parameters, no output schema, and no enum constraints — the description should explain that this is a paginated, filterable listing and what the filters mean. Instead it describes only the content, not how to constrain or page it.

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

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

Schema description coverage is only 14% — just shopId is documented — so the description must carry the load for the remaining six parameters. It adds no meaning for partId, partNumber, category, description, page, or pageSize, leaving filter and paging semantics entirely unexplained.

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

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

The description names the resource (inventory parts) and the data surfaced (availability, reorder levels, part details), so an agent can tell it retrieves part records. It does not differentiate from near-siblings like shopboss_list_order_parts or shopboss_list_part_sales, and the verb 'Review' is softer than 'List'.

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

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

There is no statement of when to reach for this tool versus the other fifteen list_* siblings, nor when not to. The only usable context — that read access depends on the API key — is a prerequisite, not selection guidance.

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

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

Annotations already carry readOnlyHint, idempotentHint and openWorldHint, yet the description still adds real value: it warns that part-sale IDs may be negative and that resource visibility depends on the API key's permissions. It stops short of describing pagination behavior or default 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?

Three short sentences, front-loaded with the operational scope before the ID quirk. The phrase 'as shown in the vendor reference' is a slight distraction but costs little.

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 six loosely documented parameters, the description should clarify what the status/writer filters accept and how paging works. It covers the safety profile and ID quirk adequately but leaves filtering and pagination behavior to guesswork.

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

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

Schema description coverage is only 17% – just shopId is documented in the schema – so the description carries most of the burden. It only clarifies that partSaleId can be negative and says nothing about status, writer, page, or pageSize semantics, leaving four of six parameters unexplained.

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 resource (part sales) and the attributes reviewed (balances and statuses), and explicitly scopes out payments and sale mutations. It does not, however, distinguish itself from nearby siblings like shopboss_list_parts or shopboss_list_order_parts, so an agent must infer which list to pick.

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?

'Review part-sale balances and statuses without taking payments or changing sales' implies a read-only review context, but no alternative tool is named and no explicit when-not condition is given. Usage is inferable 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?

The 'Read-only' sentence merely restates readOnlyHint=true, earning no credit. The added value is the authorization note that resource permissions depend on the Shop Boss API key, which tells the agent a 403/empty result may be a credentials issue rather than absent data. It says nothing about pagination behavior or result shape.

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 with the resource stated first. The 'Read-only' clause is redundant with the annotations and is the only wasted element.

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

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

For a six-parameter paginated list tool with no output schema and 17% schema coverage, the description is too thin: it never says what is returned (recommended items, declined items, or both), how paging behaves, or what an unfiltered call yields. Annotations cover the safety profile but not the operational 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 description coverage is only 17% (only shopId is documented), so the description must compensate and does not: page, pageSize, vehicleId, customerId and description are never explained. At best 'for a customer or vehicle' hints that customerId and vehicleId are optional scoping filters, leaving the semantics of the remaining parameters and the no-filter case unstated.

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 resource — recommended and previously declined repair work — and scopes it to 'a customer or vehicle', which separates it from siblings like shopboss_list_repair_orders or shopboss_list_order_parts. The verb 'Review' is softer than 'List' but the object 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?

There is no explicit statement of when to prefer this over sibling list tools, nor whether customerId/vehicleId must be supplied or what happens if neither is given. The phrase 'for a customer or vehicle' only weakly implies a filter requirement.

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, idempotentHint and openWorldHint, so "Read-only" is redundant. The description does add genuinely new context: that visibility is scoped by the Shop Boss API key's resource permissions. It says nothing about pagination behavior despite page/pageSize parameters, so the added value is modest.

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, zero filler, with the resource and return shape front-loaded and the filter keys second. Nothing repeats or pads.

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 eight parameters, no output schema and low schema coverage, the description should do more. It usefully characterizes the returned record (customer, vehicle, complaint, status) and the auth scoping, but omits pagination and date-range filtering, which an agent needs to call this correctly on large result sets.

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

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

Schema coverage is only 13%, so the description must carry the burden. It maps three of eight parameters to plain language (repairOrderId, customerId, vin), but leaves shopId, page, pageSize, statusDateFrom and statusDateTo entirely unexplained in both schema and description.

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?

"Review repair orders with customer, vehicle, complaint and status context" names a specific resource and the shape of what comes back, and the filter sentence pins down the lookup keys. It is clearly distinct from siblings like shopboss_list_appointments or shopboss_list_vehicles, though it never explicitly contrasts itself 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?

"Filter by order ID, customer or VIN" implies when the tool is appropriate (single-order lookup or per-customer/per-vehicle listing), and the API-key sentence hints at a prerequisite. But there is no explicit when-not guidance or named alternative among the 14 sibling list 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, idempotentHint, and openWorldHint, and the description merely restates 'Read-only'. The one piece of added context is the API-key permission caveat, but it says nothing about what happens when shopId is omitted, how pagination behaves, or the shape of the returned hours.

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 core purpose front-loaded and no filler. It is efficient, though the second and third sentences are thin on substance relative to the space they occupy.

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 no output schema, the description covers what is returned conceptually (opening/closing hours) and the permission model. It falls short on pagination and multi-shop scoping, which an agent needs to call this correctly.

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

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

Schema coverage is only 33% — shopId is documented, but page and pageSize are bare integers with defaults and limits only. The description does not compensate at all: no mention of paging, defaults, or whether omitting shopId spans multiple shops.

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: reviewing the shop's configured opening and closing hours. It is distinguishable from siblings like shopboss_list_appointments or shopboss_list_bays by resource alone, though it never explicitly contrasts itself 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 description gives no when-to-use guidance, no exclusions, and no mention of alternatives. 'Resource permissions depend on your Shop Boss API key' is a prerequisite note, not guidance on when this tool versus a sibling is appropriate.

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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one piece of genuine value beyond that—resource permissions depend on the API key—but says nothing about pagination behavior or how results are bounded, which matters for a 100-cap pageSize list.

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, front-loaded with the purpose. The access sentence is slightly boilerplate but earns some place by flagging variable permissions. No 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?

There is no output schema, so the description should convey what comes back; 'source labels' gives only a rough idea of the returned shape. Combined with the undescribed pagination parameters, an agent knows the intent but not how to page or parse results.

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 shopId is documented in the schema (33% coverage); page and pageSize carry no descriptions or defaults explanation in the schema, and the description does not compensate by explaining pagination semantics. The description adds no parameter meaning at all.

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 resource and action: reviewing the shop's configured customer and appointment source labels. The resource noun distinguishes it from the other list_* siblings (appointments, bays, customers, etc.), though it never explicitly contrasts 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?

No indication of when to use this versus sibling list tools, no prerequisites, and no conditions or exclusions. 'Read-only' hints at usage context but is not guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds useful context beyond them: account numbers are omitted, and resource access depends on the Shop Boss API key. It still does not explain pagination or 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?

The description is short and front-loaded with the resource and key data caveat. 'Read-only' is somewhat redundant with the readOnlyHint annotation, but overall it is efficient.

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 five-parameter paginated list tool with no output schema and low schema coverage, the description is incomplete. It covers authentication and data omission but omits filtering, pagination, and return-value expectations.

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

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

Schema description coverage is only 20%, with four of five parameters undocumented in the schema. The description mentions no parameters at all, so it does not compensate for the missing name, supplierId, page, or pageSize 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?

The description identifies the resource clearly: supplier contact details and terms. It is less explicit about the list/retrieval action and pagination, but the resource and included/omitted fields are clear enough to distinguish it from sibling list tools.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or conditions. The implied use case is reviewing supplier contact details, but the agent is left to infer the rest.

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, idempotentHint=true and openWorldHint=true, so 'Read-only' in the description is largely redundant. The genuinely additive sentence is the permission caveat ('Resource permissions depend on your Shop Boss API key'), but nothing is said about pagination behavior, result caps, or what happens when no filter is supplied.

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 capability and filter list. The 'Read-only' clause duplicates an annotation and slightly dilutes the density, but overall there is little 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 nine-parameter, zero-required query tool with no output schema and near-zero schema documentation, the description covers the main filters and the auth constraint but leaves pagination semantics, default/max page size, and filter combination behavior unexplained. Adequate to attempt a call, not complete enough to call it well.

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 only 11% schema description coverage, the description must carry weight, and it does map most filters ('ID'→vehicleId, 'owner'→customerId, plus VIN/make/model/year). However it omits three of nine parameters entirely (shopId, page, pageSize) and gives no format hints such as year being a four-digit string.

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

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

States a specific verb and resource ('Find vehicles') and enumerates the searchable fields, so an agent immediately knows this is a vehicle lookup tool. It does not explicitly contrast with siblings, but the sibling set is entirely different resources (customers, parts, repair orders), so confusion risk is low.

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 guidance on when to use this versus e.g. shopboss_list_customers (which may also surface vehicle data), nor on whether filters combine as AND, whether any filter is required, or how to page. The only contextual note is the permission caveat, which is not usage guidance.

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