Shopmonkey MCP by usefulapi

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

Annotations declare destructiveHint=true, and the description adds essentially nothing on top: it does not say whether an existing primary email is replaced, whether duplicate addresses are rejected, what permissions are required, or what the response contains. Only the optional primary flag adds slight behavioral color.

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 with the purpose front-loaded; the trailing 'Shopmonkey: POST /v3/customer/:id/email' is essentially redundant with the schema's customerId/email params but costs little and confirms the target resource.

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 mutating tool with a destructiveHint, five parameters, and no output schema, the description leaves key questions unanswered: what happens to the prior primary address, what a duplicate email does, and what the call returns. The agent has enough to call it, but not enough to predict its effects.

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 (email, primary, customerId, locationId, subscribed) are already documented in the schema. The description restates only the 'primary' option without adding format or behavioral 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+resource ('Add an email address to an existing customer') and clarifies the optional primary semantics. It implicitly distinguishes itself from create_customer/update_customer, but never names a sibling, so it stays at 4 rather than 5.

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

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

The phrase 'to an existing customer' hints at the precondition that the customer must already exist, but there is no explicit when-to-use guidance and no reference to alternatives such as update_customer or create_customer for other cases.

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

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

Annotations supply only destructiveHint=true, so the description carries most of the behavioral burden. It does add non-obvious context that customer messaging is opt-in via explicit flags, which the per-field schema text conveys only piecemeal. It says nothing about whether the appointment can be edited afterwards, required permissions, or the conflict/error behavior of double-booking a slot.

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

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

Two tight sentences: the purpose and the optional linkage set come first, the notification caveat second, with the raw API endpoint as a trailing detail. Nothing is padded, though the 'POST /v3/appointment' fragment is redundant for an agent that only needs the tool name.

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 14-parameter creation tool with no output schema and only destructiveHint in annotations, the description covers the conceptual shape well but is thin on outcomes: it does not say what is returned (e.g. the new appointment id) or what happens on scheduling conflicts. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so every one of the 14 parameters is already documented in the schema, making 3 the baseline. The description only adds the framing that customer/vehicle/order/technician links are optional and co-dependent, without format 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 and resource ('Book an appointment on the shop calendar') and enumerates the optional linkages (customer, vehicle, order, technicians). It does not name or contrast with the sibling shopmonkey_search_appointments, so an agent must infer the create-vs-find split from the 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?

'Confirmation/reminder messages are only sent if you ask' is a genuine usage rule about opt-in notifications, which is helpful. But there is no guidance on when to book versus when to use create_order or search_appointments, and no prerequisites (e.g. needing existing customer/vehicle ids) 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 declare destructiveHint=true, which is counterintuitive for a create and left unexplained; the description adds the useful two-step workflow (email added separately), but says nothing about only customerType being required, permissions, duplicate handling, or what the call returns. Some value beyond annotations, but the behavioral picture is thin.

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

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

Three short clauses, front-loaded with the verb and resource, no filler. The trailing endpoint reference is marginal but harmless; overall appropriately sized.

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 18-property create with no output schema, the description should ideally say what the call returns (e.g., the new customer id) and note that only customerType is mandatory. It covers the workflow hand-off but leaves the agent to infer the response and required-field reality from the schema.

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

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

Schema description coverage is 100%, so the schema already carries parameter meaning. The description's 'a person or a fleet account' phrasing loosely mirrors the customerType enum without adding format or constraint detail, so baseline 3 applies.

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

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

States a specific verb (Create) and resource (customer), and explicitly disambiguates the two variants it produces: a person or a fleet account. It also names the sibling used to complete the workflow, so an agent can separate it from add_customer_email without opening either schema.

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

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

Gives clear sequencing context – create the customer first, then add an email via shopmonkey_add_customer_email – which is real when-to-use guidance. It does not state exclusions (e.g., use find_customers_by_email first to avoid duplicates), so it falls 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?

The destructiveHint=true annotation is generic and the description adds genuine context that the created entity is an estimate-stage work order, not a completed one. However, it omits who can create orders, whether the resulting order id is returned, and any prerequisite lookups, so behavioral coverage is only moderate.

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 action and the estimate semantics; the endpoint mapping is minor filler but the rest 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 10-parameter mutation tool with no output schema and no readOnly/destructive nuance beyond a hint, the description covers the core action but leaves the return value, the all-optional parameter set, and prerequisite ID lookups for the schema and sibling tools to handle.

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 each of the 10 properties is documented in the schema itself, including cross-references to sibling tools for locationId and workflowStatusId. The description adds only the implication that customer and vehicle are essential, despite the schema marking nothing required, so baseline 3 applies.

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

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

States a specific verb and resource ('Open a new work order') plus an important scope clarification: it begins as an estimate, not a finalized order. The customer+vehicle scoping distinguishes it from shopmonkey_create_appointment, though it does not name that sibling explicitly.

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

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

'Add services in the Shopmonkey UI' is a useful constraint implying services cannot be attached through this call, but there is no explicit guidance on when to create an order versus an appointment or how to obtain customerId/vehicleId first. Usage is implied 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 only supply destructiveHint=true; the description does not disclose whether a duplicate VIN is rejected, what the response contains (e.g. the new vehicle id), required permissions, or side effects on the linked customer record. The 'POST /v3/vehicle' note is an implementation detail rather than behavioral context.

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

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

Two short sentences with the purpose front-loaded; the trailing HTTP endpoint reference adds little for an agent and is the only mild 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 15-parameter mutation tool with no output schema and sparse annotations, the description omits what the call returns and how a created vehicle is subsequently referenced. An agent can construct the request from the schema but learns nothing about the result it will get back.

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% across 15 parameters, so the schema already documents each field's meaning and the two enums. The description adds only the optional customer linkage, which is a modest supplement over the schema 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?

States a specific verb and resource ('Create a vehicle') and clarifies that the vehicle may optionally be attached to a customer. It does not explicitly distinguish itself from siblings like shopmonkey_update_order or shopmonkey_get_vehicle, though the create semantics are 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?

No guidance on when to use this tool versus alternatives, nor prerequisites such as needing an existing customer before attaching one. The phrase 'optionally attached to a customer' hints at the customerId relationship but gives no conditions 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?

readOnlyHint=true already tells the agent this is a safe read, so the description carries less burden. It adds the upstream endpoint (POST /v3/customer/email/search), which hints at batch semantics, but says nothing about result cardinality, pagination, or the interaction between the email list and excludeCustomerId.

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 front-loads the purpose before the trailing endpoint reference. The API path is mildly redundant but short and confirmatory rather than wasteful.

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

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

For a two-parameter read-only lookup with no output schema, the definition is minimally adequate: it explains the match semantics but not what a result contains or how many can come back. An agent could call it correctly, but not predict the response shape.

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

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

Schema coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description does add real value by clarifying that a customer matches if they own ANY of the supplied addresses (OR semantics rather than AND), but excludeCustomerId's behavior is left entirely to 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 (find) and resource (customers) with a clear qualifying dimension (by email), and the batch semantics 'that own any of the given email addresses' is precise. It distinguishes itself implicitly from shopmonkey_find_customers_by_phone and shopmonkey_search_customers by the email key, though it never names those alternatives.

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

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

There is no when-to-use guidance and no routing to alternatives, despite several close siblings (search_customers, find_customers_by_phone). The agent must infer that this is the email-keyed lookup path rather than a general search.

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, so the bar is lower. The description adds the meaningful union semantics ('own any of the given phone numbers'), but says nothing about pagination, result limits, or what happens when no match exists; the endpoint string is implementation detail, not 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?

Single front-loaded sentence stating purpose plus a short scoping clause, then the backend endpoint. It is tight, though the 'Shopmonkey: POST /v3/...' tail is implementation leakage that adds little for 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?

Only two parameters, 100% schema coverage, no output schema, and a read-only annotation – so the description need not explain returns. It supplies the key semantic ('any of the numbers') and enough context to call correctly; only alternative-routing guidance 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% and both parameters (phoneNumbers, excludeCustomerId) are documented in the schema, so the schema does the heavy lifting. The description adds no format or matching semantics beyond what the schema already states, which is the baseline 3 case.

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 (Find) plus resource (customers) and the discriminator (by phone number 'that own any of the given phone numbers'). It is clear what the tool returns, but it never names or contrasts against close siblings like find_customers_by_email or search_customers, so an agent still infers the boundary from the tool 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?

The phrase 'the usual way to identify a caller' implies a caller-lookup scenario, but there is no explicit when-to-use/when-not, no prerequisite, and no routing to the email or general-search alternatives present in the sibling list. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value beyond that: it explains the identity is scoped to the API key, that no arguments are needed, and that it is inexpensive — useful context for probing auth.

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

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

Two tight sentences: purpose and payload first, then the practical reason to call it, plus the raw endpoint for reference. 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?

No output schema exists, yet the description lists the returned fields and the endpoint, which is everything an agent needs for a simple no-param read. Nothing material 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?

Zero parameters, so the baseline is 4. Nothing is required from the caller, and the description correctly implies this is a no-argument call.

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 precise verb+resource ('Fetch the user this API key acts as') and enumerates the returned fields (id, name, company, default location, permissions). It is clearly distinguishable from the sibling shopmonkey_list_users, which enumerates other users.

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 usage context: a cheap way to confirm the key works and to find your locationId. It lacks an explicit exclusion (e.g. 'use list_users to enumerate others'), but the intended use 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, non-mutating read, so the bar is lower. The description adds the returned field groups, but says nothing about 404/not-found behavior, id formats, or auth requirements beyond the endpoint path.

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: the capability plus its return payload, then the underlying endpoint. Front-loaded, zero filler, and the trailing 'GET /v3/customer/:id' aids mapping without bloating the text.

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

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

With no output schema, the description usefully compensates by naming the field groups returned. For a one-parameter read-only tool this is nearly sufficient; only error/not-found semantics are omitted, a minor gap.

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

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

Schema description coverage is 100% for the single customerId parameter, so the baseline is 3. The description confirms the id is what identifies the record but adds no format, prefix, or sourcing detail (e.g., where an agent obtains a valid id) 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 ('Fetch a single customer by id') and enumerates the payload it returns (contact details, emails, phones, vehicle/order/appointment counts). The 'single ... by id' framing cleanly separates it from shopmonkey_search_customers, find_customers_by_email, and find_customers_by_phone 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?

'By id' implies the caller must already hold a customer id, which faintly contrasts with the lookup-style siblings, but the description never names those alternatives or states when to prefer this over search_customers/find_customers_by_*. 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds value beyond that by naming the returned fields and stating that totals are in cents and that payment state is included. That return-shape disclosure is meaningful given there is no output schema. It stops short of noting what happens for an unknown id.

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

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

A single dense sentence that front-loads the verb and resource before the payload list, plus a compact endpoint reference. No filler, no redundancy, and the most important information arrives first.

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 one required parameter, a readOnly annotation, and no output schema, the description covers the essentials and partially compensates for the missing output schema by enumerating returned fields. Missing only error behavior for a non-existent order id.

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 the single orderId parameter, so the schema already documents it fully. The description adds only 'by id', which merely restates the parameter rather than supplying format, prefix, or example values. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Fetch a single work order by id') and immediately enumerates the payload (customer, vehicle, complaint, totals, payment state, profitability). The word 'single' cleanly separates it from the sibling list tools such as shopmonkey_list_orders and shopmonkey_list_customer_orders.

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

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

Usage is implied by 'by id' and 'single', which signals retrieval-by-identifier rather than listing or updating, but the description never explicitly states when to prefer this over shopmonkey_list_orders or shopmonkey_list_customer_orders, nor any prerequisites. Adequate but leaves the routing inference to the agent.

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 bar is lower. The description does add real value by disclosing the response scope (mileage and tire-pressure logs), which is useful since there is no output schema. It says nothing about 404/error behavior, auth scope, or rate limits.

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

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

A single front-loaded sentence states the operation, the input, and the returned data. The trailing 'Shopmonkey: GET /v3/vehicle/:id' is redundant for an agent but cheap and aids API traceability, so it does not meaningfully detract.

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

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

For a single-parameter read tool with readOnlyHint set and no output schema, the definition covers purpose, input, and the notable parts of the return payload. The remaining gap — error behavior when the id is unknown — is minor at this complexity level.

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 the schema already documents it at 100% coverage ('The vehicle id.'). The description's 'by id' confirms rather than extends the schema, so baseline 3 is appropriate — there is no format, prefix, or sourcing detail added.

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) plus resource (a single vehicle) and the key identifying input (id), and adds what the payload carries (mileage and tire-pressure logs). It implicitly separates itself from list_customer_vehicles by saying 'single', but never names that sibling, so differentiation is inferential 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?

'by id' implies the usage context: you already have a vehicleId and want the full record. There is no stated when-not, no mention of list_customer_vehicles as the alternative when you lack an id, and no prerequisites or error handling 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?

readOnlyHint=true already establishes the safety profile, but the description adds real value by disclosing the returned payload shape: labor, parts, fees and a total expressed in cents. This matters because there is no output schema to convey it. It omits pagination behavior, though the schema's skip/limit descriptions partly cover 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 well-formed sentence with the resource described up front, followed by a compact API reference. The 'Shopmonkey: GET /v3/canned_service' tail is minor filler that an agent can't act on, but it costs almost 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?

For a simple read-only list tool with no output schema, the description covers both what is returned and the unit of the monetary total. Combined with fully documented paging parameters and read-only annotations, an agent has what it 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 description coverage is 100% and both skip and limit are documented in the schema, so the description correctly need not restate them. It adds no parameter meaning beyond the schema, which is the baseline case.

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 (canned services), and parenthetically defines the resource as reusable job templates, which meaningfully separates it from sibling tools like shopmonkey_list_order_services. It does not, however, explicitly route the agent against any sibling by name.

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

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

The description gives no when-to-use guidance, no prerequisites, and no named alternative for the order-scoped counterpart (list_order_services). All it conveys is the what, leaving the agent to infer when this list is the right one.

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 domain context about what an 'order' comprises and the underlying endpoint, but says nothing about pagination behavior, ordering, or result volume beyond what the schema supplies.

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 purpose and resource definitions come first, the endpoint reference last. No filler or redundancy.

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

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

For a read-only, single-required-param list tool with full schema coverage, the description covers what the tool returns conceptually and how to scope it. Explicit routing versus list_orders/get_order is the only real omission.

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 customerId, skip and limit are all documented in the schema. The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and scoped resource (a customer's work orders) and usefully expands the domain term 'orders' into estimates, repair orders and invoices. It does not explicitly name the unfiltered sibling shopmonkey_list_orders or shopmonkey_get_order, so sibling differentiation stays implicit.

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 'their service history' hints at the intent (viewing a customer's past work), which implies usage, but there is no explicit when-to-use, when-not-to-use, or alternative routing to list_orders/get_order.

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 underlying endpoint and the fields that come back, which is meaningful since there is no output schema, but it says nothing about pagination behavior or result ordering beyond what the schema's skip/limit already imply.

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

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

Two tight sentences with the core purpose front-loaded and the API mapping trailing as supporting detail; nothing is wasted.

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

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

For a simple read-only list tool, the description covers purpose, scope, and return fields, and the schema covers paging. No output schema exists, so the field enumeration helps, though paging/result-size expectations could be stated more explicitly.

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 skip, limit, and customerId all documented in the schema. The description only alludes to the customer scoping and adds no format or syntax detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (vehicles) with the scoping relation (owned by a customer), and enumerates the returned fields (year/make/model, VIN, plate, mileage). This clearly separates it from the singular shopmonkey_get_vehicle and the write-path shopmonkey_create_vehicle.

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 'owned by a customer', so an agent can infer this is the per-customer vehicle listing, but there is no explicit when-to-use guidance or naming of alternatives such as shopmonkey_get_vehicle for a single vehicle.

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

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

With readOnlyHint=true the safety profile is already covered, but the description usefully adds what the read returns: order number, status flags, totals in cents, workflow status, assigned technicians, plus the fact that results are paged. It stops short of describing pagination defaults or result-count 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?

Three short sentences, front-loaded with the core action, then the routing hint, then the endpoint. Nothing is padded and the ordering matches how an agent would consume 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?

With no output schema, the description carries the return-shape burden and does describe the salient fields, and annotations cover safety. Minor gaps remain: no default limit/pagination behavior and no indication of what the shop scope implies for result volume.

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

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

Schema description coverage is 100% and both skip/limit are fully documented there, so the baseline is 3. The description's 'paged' wording reinforces their purpose but adds no format or default-value 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?

Specific verb + resource with scope: 'List work orders for the shop, paged.' It immediately names the sibling it is not (shopmonkey_list_customer_orders), so an agent can distinguish it from the customer-scoped variant without opening either schema.

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

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

Explicit routing rule: 'For one customer's orders use shopmonkey_list_customer_orders,' which gives the agent a clear alternative and the condition that selects it. It does not, however, state any other scope caveats or prerequisites (permissions, default page size when limit is omitted).

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

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

The readOnlyHint annotation already establishes this is a safe read. The description usefully spells out the breadth of the payload (line items, authorization status, totals), but discloses nothing about pagination, rate limits, permissions, or ordering, so it adds only modest behavioral context.

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

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

Two tight sentences, front-loaded with the resource and its contents. The trailing endpoint mapping is arguably redundant for an MCP caller but costs little and aids agents familiar with the underlying API.

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 carries the burden of telling the agent what comes back, and it does so by enumerating the line-item categories, authorization status, and totals. Missing only details like pagination or result ordering, which keeps it short of a 5.

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

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

Only one parameter, and schema coverage is 100% with the schema describing it as 'The order id.' The description adds that it is scoped to a 'work order' and gives the REST path /v3/order/:orderId/service, but no format or acquisition guidance beyond that. 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 the services (jobs) on a work order') and enumerates the contents (labor, parts, tires, fees, subcontracts, authorization status, totals). It is clear on its own, but never differentiates itself from siblings like shopmonkey_get_order or shopmonkey_list_orders, which plausibly overlap.

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

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

There is no when-to-use guidance, no statement of prerequisites beyond the required orderId, and no mention of alternatives such as get_order or list_orders. An agent must infer the use case purely from the tool name and the returned-field list.

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 burden is lighter. The description adds the underlying endpoint (GET /v3/user) and the role composition of the result, but says nothing about default page size, whether the full roster is returned in one call, 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?

A single sentence plus an endpoint tag, front-loaded with the verb and resource. No filler, no restatement of the title, and the most decision-relevant detail (the ids are for technicians/service writers) sits before the endpoint reference.

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 full parameter documentation and a readOnly annotation, this covers what an agent needs to decide and call. The only gap is return-shape detail — it hints that ids are the payload but doesn't say what else each user record contains, and there is no output schema to fall back on.

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

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

Schema description coverage is 100% and both parameters (skip, limit) are documented in the schema with ranges and usage notes, so the description need not repeat them. It adds no paging semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('List the shop's users') and enumerates the roles returned (service writers, technicians, admins), which tells an agent exactly what domain object comes back. It also distinguishes itself from shopmonkey_get_current_user by scoping to the whole shop rather than the caller.

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 clause 'the ids to use for technicians and service writers' makes the downstream usage explicit — an agent knows to call this before setting technician/service-writer fields elsewhere. There is no when-not guidance or named alternative, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the cross-tool linkage and the fact that statuses come back with a position, but says nothing about ordering, default page size, or what happens when skip/limit are 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?

Three short sentences, with the core purpose front-loaded and the actionable cross-reference immediately after. The trailing 'Shopmonkey: GET /v3/workflow_status' endpoint note is mild restatement but cheap and unambiguous.

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-parameter list tool with no output schema, the description supplies purpose, domain framing, a key return field, and the follow-up action. Only pagination/ordering behavior for the returned list is left unspecified, which is a minor gap.

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

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

Schema description coverage is 100% and both parameters (skip, limit) are fully documented in the schema, so the baseline is 3. The description mentions no parameter behavior of its own; 'position' refers to returned data, not to an input.

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 workflow statuses') and adds real domain meaning by glossing them as 'the columns of the shop's work-order board' and noting they carry a position. No sibling lists workflow statuses, so the resource is inherently distinguishable, though no sibling is named.

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

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

The second sentence gives a concrete downstream use: take the id and move an order via shopmonkey_update_order, which tells the agent when this tool is the right prerequisite. It stops short of stating when not to use it or naming an alternative listing 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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds that results include the associated customer, which is useful context, but it says nothing about pagination behavior, default result limits, or whether all supplied filters are ANDed together.

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 functional sentences with the scope and filters front-loaded, followed by the endpoint mapping. The 'Shopmonkey: POST /v3/appointment/search' line is low-value for an agent that never calls HTTP directly, but it is short and does not distract.

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 11-parameter read-only search with no output schema, the description covers what is returned (appointments with their customer) and the filter space, and the schema fully documents every parameter including paging and sort. Only the interaction rules between filters and pagination defaults are left unstated, which is a minor gap.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in the schema, setting the baseline at 3. The description's filter list (date range, customer, order, technician) maps onto some parameters but omits paging (skip/limit), sort, and includeUnassigned, adding no syntax or format 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?

The description names a specific verb and resource ('Search the appointment calendar') and enumerates the filter axes (date range, customer, order, technician). It is clearly distinct from write siblings like shopmonkey_create_appointment, though it never explicitly contrasts itself with the other list/search tools such as shopmonkey_search_customers or shopmonkey_list_orders.

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

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

Usage is implied by the listed filter dimensions: an agent can infer it should use this tool when it has any of those keys. However, there is no explicit when-to-use guidance, no statement of how filters combine, and no mention of alternatives (e.g., get_order or list_customer_orders when appointments are wanted in an order 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?

Annotations already declare readOnlyHint=true, so safety profile is covered. The description adds that filtering/sorting/paging are server-side and that emails and phone numbers are returned, which is genuine additional context. But it omits pagination defaults (e.g., what happens with no limit) and total-count 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?

Three short sentences, front-loaded with purpose, then return detail, then the underlying endpoint. Zero 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?

Adequate for a read-only search tool with a rich schema and annotations covering safety. The main gap is the lack of routing guidance among the many customer-related siblings, but the core search behavior is fully described.

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

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

Schema coverage is 100%; the schema documents skip, limit, where, and orderBy in detail including examples. The description restates the server-side filter/sort/paging concept without adding syntax 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?

Clearly states the verb and resource: 'Search customers' with server-side filter, sort and paging. Distinguishes from find_customers_by_email/phone implicitly by describing generic filtering, though it doesn't explicitly name those siblings as alternatives.

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 usage when the agent needs to filter/sort/page over customers, but gives no explicit when-to-use vs find_customers_by_email, find_customers_by_phone, or get_customer. The generic nature suggests broad search, but exclusions are 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by disclosing the underlying endpoint (POST /v3/inventory_part/search) and showing a filter shape, but it says nothing about result volume, pagination defaults, or cost-unit handling ('in cents' is stated for cost fields). 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?

Front-loaded with what can be searched and what fields come back, followed by a filter example and the API path. No filler sentences, though the dense field enumeration is close to being a data dump rather than prose.

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

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

With no output schema, the description usefully compensates by listing the fields an agent can expect back, and 100% schema coverage handles the inputs. The main remaining gap is paging/return-size expectations for a search endpoint, which matters more given the absence of an 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%, so the four parameters (skip, limit, where, orderBy) are already documented in the schema. The description reinforces the where parameter with a concrete {"sku": "ABC-123"} filter example, but adds no guidance on paging or sorting beyond what the schema provides. 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?

The description gives a specific verb (Search) and resource (parts inventory) and enumerates the fields exposed — name, part number, SKU, quantities, retail/wholesale cost, bin, brand, vendor. This is well beyond a tautology. It does not need to differentiate from siblings since no other tool touches inventory parts, but it stops short of a 5 by not stating the distinguishing scope in one crisp clause.

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 'Search the parts inventory' plus the filter example, which shows an agent how to scope results. However, there is no explicit when-to-use, when-not-to-use, or reference to any alternative tool, and no mention of how to page through large result sets.

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

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

Annotations supply destructiveHint=true, and the description adds genuinely useful behavioral context beyond them: 'Only the fields you pass are sent' clarifies that this is a partial update that leaves unspecified fields intact, which resolves the PUT-replacement ambiguity, plus the underlying endpoint. It does not mention permission/auth requirements, but with annotations covering the mutation profile this is solid.

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 waste; the partial-update constraint and the endpoint mapping are front-loaded and each sentence carries distinct information.

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

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

For a 17-parameter mutation the description is thin: it neither mentions the breadth of updatable fields nor flags risky inputs, and with no output schema present it says nothing about what comes back. The partial-update note and endpoint are the right essentials, but a caller still has gaps around response and permissions.

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 baseline is 3. The description names a few editable fields but adds no format, allowed-value, or default detail beyond what the schema already documents (enums for preferredLanguage/preferredContactMethod, bounds on discountPercent, etc.).

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?

Clear verb+resource ('Update a customer') with the category of editable fields named, and it is unambiguously distinct from create_customer, get_customer and update_order by sibling name alone. The field list ('name, address, note or preferences') is only a partial subset of the 17 schema properties, so the scope statement is slightly under-inclusive.

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 versus alternatives such as create_customer, get_customer, or find_customers_by_*; the only hint is the required customerId in the schema. An agent gets no when/when-not framing or precondition (e.g., the customer must already exist).

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 carry destructiveHint=true; the description supplements this with partial-update semantics ('only the fields you pass are sent'), the archive/unarchive behavior, and the underlying PUT /v3/order/:id contract. It stops short of disclosing permission requirements, reversibility of archive, or side effects on related entities.

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, front-loaded with the action and the mutable surface, closing with the API mapping. No filler, though the enumerated field list is somewhat redundant with the schema.

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

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

For a 12-parameter mutation tool with no output schema, the description covers the mutation surface and the partial-payload rule, which is the main thing an agent must know. Gaps remain around failure modes, permissions, and whether archived state blocks further edits.

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 is already documented, including the status enum and the cross-reference to list_workflow_statuses. The description's field list largely restates the schema rather than adding format, default, or interaction semantics, 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 and resource ('Update a work order') and enumerates exactly which facets can be changed (workflow status, status enum, complaint/recommendation, due date, service writer, archive), which cleanly separates it from create_order, get_order, and list_orders.

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

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

The line 'Only the fields you pass are sent' is a useful patch-semantics cue, and the workflowStatusId field points at shopmonkey_list_workflow_statuses as a lookup. However there is no explicit when-to-use versus when-not-to-use guidance, no prerequisites (e.g. permissions, whether archived orders are editable), and no routing to a sibling for related operations.

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