shopmonkey

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

Annotations declare destructiveHint=true, yet the description never explains what is destructive—whether adding an email replaces an existing primary, how duplicates are handled, or whether permissions are required. It effectively only restates the operation and appends the REST endpoint, adding little behavioral context beyond the annotation.

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

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

Two tight sentences with the core action front-loaded and no filler. The endpoint mapping is a compact extra rather than padding, though it contributes little to selection.

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 add-email mutation with no output schema, the description covers the essential action, but it omits failure modes (duplicate address, missing customer), the meaning of the destructive annotation, and how primary/subscribed interact—gaps an agent would want before invoking.

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, establishing a baseline of 3. The description echoes the primary/optional concept but adds no format, validation, 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 ('Add an email address to an existing customer') and clarifies the optional primary-address scope. It is distinguishable from read siblings like find_customers_by_email, though it does not explicitly contrast with update_customer, which could also modify emails.

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 notes the 'optionally as their primary address' case but gives no when-to-use guidance, no prerequisites (e.g., the customer must already exist beyond the phrase 'existing customer'), and no direction toward alternatives such as update_customer.

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 only annotation is destructiveHint=true, which the description neither explains nor contradicts. What the description does add is meaningful beyond the annotations: outbound SMS/email side effects are opt-in ('only sent if you ask'), which is exactly the kind of behavioral fact an agent needs to avoid spamming customers.

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-load the purpose and the messaging caveat, with the raw endpoint appended as a developer breadcrumb. Nothing is redundant, though the trailing 'Shopmonkey: POST /v3/appointment' adds little for an agent choosing the tool.

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 mutation with no output schema and a bare destructiveHint annotation, the description covers the core behavior but omits a couple of dependencies an agent should know (e.g., that sending reminders/confirmations presumably requires a customer, and why the operation is flagged destructive). It is adequate but not fully self-sufficient.

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

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

Schema description coverage is 100%, so all 14 parameters (including required name/startDate/endDate, ISO 8601 formats, enum color, and the send flags) are already documented in the schema. The description only summarizes the association fields, adding no syntax or default detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Book an appointment on the shop calendar') plus the optional associations (customer, vehicle, order, technicians), so the agent knows exactly what is created. It does not explicitly contrast itself with the sibling shopmonkey_search_appointments, but the create-vs-search distinction is inferable from the verb.

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

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

The description implies usage through 'optionally for a customer, vehicle and order', and it adds the useful condition that confirmation/reminder messages are only sent if requested. However, it never states when to book via this tool versus, say, creating an order first, nor whether linking customer/vehicle/order is preferred or required for follow-up messaging.

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

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

Annotations declare only destructiveHint=true; there is no readOnly guarantee or idempotency info. The description adds the raw endpoint (POST /v3/customer) and the email follow-up, but says nothing about duplicate handling, required permissions, whether locationId defaults to the caller's location, or what happens if the same customer already exists — real gaps for a creating mutation.

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

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

Three short sentences, front-loaded with the core action and zero filler. The trailing endpoint string is minor noise but the rest 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?

Adequate to call the tool: purpose, entity modes, and the email chaining step are all present, and the schema documents every field with no output schema to explain. Still missing any note on duplicate prevention or what the call returns (e.g., a customer id needed for the follow-up email call), which an agent creating then linking records would want.

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% across all 18 parameters, so the schema carries the semantics; baseline 3 applies. The description's only added value is the person-vs-business framing of customerType, which the schema already documents in its enum 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?

States a specific verb and resource and clarifies the two entity modes ('a customer (a person) or a fleet account'), which maps onto the customerType enum and distinguishes it from the other create_* siblings. It does not, however, explicitly differentiate itself from update_customer or search_customers beyond the verb.

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 one sequencing instruction — add an email afterwards via shopmonkey_add_customer_email — which is genuinely useful for chaining. It offers no guidance on prerequisites (e.g., checking for duplicates with find_customers_by_email) or when to prefer Fleet over Customer beyond the parenthetical.

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 and a title. The description adds genuine behavioral value by disclosing that the order starts as an estimate and that services must be added in the UI, but it omits auth/permission needs and does not clarify that all ten inputs are optional.

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-load the action and the estimate nuance, with the API route appended as compact metadata. Nothing is padded, though the trailing 'Shopmonkey: POST /v3/order' is of marginal use to an agent.

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

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

For a ten-parameter creation tool with zero required fields, no output schema, and only a destructiveHint annotation, the description should indicate which fields are needed for a valid order and whether a partial payload succeeds. It covers the workflow hint but leaves the creation contract underspecified.

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 cross-references to shopmonkey_get_current_user and shopmonkey_list_workflow_statuses. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Open a new work order') and scopes it ('for a customer and vehicle'), plus a useful nuance that it begins as an estimate. It implicitly separates itself from create_appointment/create_customer siblings but never names 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 line 'Add services in the Shopmonkey UI' conveys a real constraint (services cannot be added via this call) and implies workflow context. However, there is no explicit when-to-use guidance relative to shopmonkey_create_appointment or shopmonkey_update_order, and no stated prerequisites.

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 destructiveHint=true, so the write nature is disclosed structurally; the description adds only the raw endpoint 'POST /v3/vehicle'. It says nothing about authorization requirements, whether the created vehicle is returned, or what happens if a duplicate VIN 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 clauses, front-loaded with the action and scope; nothing is padded. It is efficient, though the trailing 'Shopmonkey: POST /v3/vehicle' is internal API trivia 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?

For a 15-parameter mutation with no output schema and a destructive annotation, the description is thin. It never tells the agent what a successful call yields (e.g. the new vehicle id) or how the optional customer linkage affects the result, leaving meaningful gaps for a create operation of this size.

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 all 15 parameters, so the schema carries full documentation burden and the baseline is 3. The description adds nothing parameter-specific beyond hinting that customerId is optional, so it does not exceed the baseline.

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

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

States a specific verb (create) and resource (vehicle) plus the scoping nuance that the vehicle may optionally be attached to a customer. This distinguishes it from shopmonkey_get_vehicle and shopmonkey_list_customer_vehicles, though it does not explicitly name any sibling the way the strongest definitions do.

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

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

The only usage signal is 'optionally attached to a customer', which implies customerId is optional but not when to supply it. There is no guidance on prerequisites, no mention of related flows (create_customer, get_current_user for locationId), and no statement of when to use this over other creation 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?

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying API route (POST /v3/customer/email/search), which is mildly useful, but does not describe return behavior, no-match handling, or pagination. With annotations covering safety, this is a reasonable but thin extra layer.

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 primary action front-loaded and the API route trailing as secondary metadata. Every part earns its place and 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 lookup with full parameter coverage and readOnlyHint, the description gives enough to call the tool correctly. It does not explain result shape or no-match behavior, and there is no output schema, but those gaps are minor for this tool's complexity.

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 adds the important semantic that the tool matches customers who own 'any of the given email addresses', clarifying OR semantics across the array beyond the schema's generic 'Email addresses to look up'. The excludeCustomerId parameter is not described, but the schema already documents it.

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 verb ('Find'), resource ('customers'), and scope ('by email addresses'), and the sibling tools include find_customers_by_phone and search_customers, so the distinction is clear. An agent can identify this as the email-based customer lookup without opening the schema.

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

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

The description implies usage when email addresses are available, which is adequate context. However, it does not explicitly name when to prefer this over search_customers or find_customers_by_phone, nor does it state any exclusions or prerequisites.

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 only needs to add beyond that. It contributes the caller-identification framing and the underlying endpoint, but says nothing about result behavior (e.g., partial matches, empty results, or the 50-number cap's effect).

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, front-loaded sentences with no wasted prose; the purpose comes before the endpoint citation. The raw 'POST /v3/customer/phone_number/search' reference is boilerplate rather than agent-facing signal.

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 should ideally convey what comes back (a list of matching customers, possibly empty). It covers the input side adequately and the read-only nature is annotated, but the return shape remains unspecified.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, establishing the baseline of 3. The phrase 'any of the given phone numbers' usefully implies OR-matching across the array, but the excludeCustomerId filter is not elaborated on in the 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?

States a specific verb ('find') plus resource ('customers') and the identifying key ('phone numbers'), so the operation is unambiguous. It does not explicitly contrast with the very similar siblings shopmonkey_find_customers_by_email and shopmonkey_search_customers, leaving the differentiation to the agent.

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 usual way to identify a caller' hints at the intended scenario (inbound caller lookup), which is useful context. However, there is no stated when-not-to-use or explicit routing to the email-based or general search siblings.

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

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

readOnlyHint=true already declares the safety profile, but the description adds real context beyond it: the result is scoped to the calling API key's identity, the response fields are enumerated, and calling it is framed as 'cheap' (no meaningful cost/side effects). It does not discuss error behavior (e.g. whether an invalid key surfaces as an error here), which keeps it at 4.

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

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

Two sentences, front-loaded with what is returned before the rationale, and it closes with the REST endpoint for traceability. No filler or repetition of the title.

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

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

With no input parameters and no output schema, the description carries the whole burden and does so by listing the returned fields, which an agent otherwise could not know. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, which sets the baseline at 4; there is nothing for the description to disambiguate. It correctly avoids inventing parameter guidance that does not exist.

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

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

States a specific verb and resource ('Fetch the user this API key acts as') and enumerates the returned fields (id, name, company, default location, permissions). The key-scoped framing cleanly distinguishes it from the sibling shopmonkey_list_users, which returns a collection rather than the identity behind the credential.

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?

Explicitly gives two use cases: 'a cheap way to confirm the key works and to find your locationId.' This tells an agent when the tool is worth calling. It stops short of naming an alternative to use instead in other situations (e.g. list_users for enumerating teammates), so it is a 4 rather than a 5.

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

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

readOnlyHint=true already establishes this is a safe, non-mutating read. The description adds genuine value beyond that by enumerating the returned content (contact details, emails, phone numbers, vehicle/order/appointment counts), which matters since there is no output schema. It omits error behavior for an unknown id, keeping it out of 5 territory.

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

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

One front-loaded sentence carrying the key, the returned payload, and the underlying endpoint — every clause earns its place with no filler.

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

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

For a single-parameter read tool with no output schema, naming the fields it returns is what the agent needs and the annotations already cover safety. It lacks any note on not-found behavior, which is a minor gap rather than a blocking one.

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, and the description only restates it as 'by id' with no format, prefix, or lookup semantics. Baseline 3 applies when the schema fully documents the 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 (fetch) and resource (a single customer) plus the lookup key (id) and the endpoint. 'By id' distinguishes it from the sibling search_customers, find_customers_by_email, and find_customers_by_phone, so an agent can route correctly without opening a schema.

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

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

The 'by id' framing makes the selection condition clear: use this when you already have a customer id, versus the search/find siblings when you don't. It never explicitly names those alternatives or states an exclusion, so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description still adds real value by naming the returned fields and their units ('parts/labor/tax in cents'), which matters because no output schema exists. It does not cover error behavior (missing/invalid id) or permissions, keeping it short of a 5.

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

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

One front-loaded sentence covering identity, lookup key, and return contents, followed by the underlying endpoint for traceability. Nothing is padded or repeated.

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

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

With no output schema, the description correctly compensates by summarizing the response payload and its units, which is the main thing an agent needs for a single-resource read. Missing only edge-case behavior (not-found handling) and explicit sibling routing, so it falls just short of complete.

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

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

There is a single required orderId with 100% schema description coverage, so the schema already carries the parameter contract. The description adds no format, prefix, or sourcing detail beyond 'by id', 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 resource ('Fetch a single work order by id') and immediately enumerates the returned surface (customer, vehicle, complaint, totals, payment state, profitability). The word 'single' plus 'by id' clearly separates it from shopmonkey_list_orders and differentiates the read from shopmonkey_update_order.

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

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

Usage is only implied: 'by id' signals an order id must already be known, so an agent can infer it should follow a list/search call. However, the description never states when to prefer this over shopmonkey_list_orders or shopmonkey_list_customer_orders, and gives no exclusions or prerequisites.

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 usefully discloses that the response includes mileage and tire-pressure logs, which is real behavioral context, but says nothing about auth requirements, error behavior for missing ids, or response shape beyond those two log types.

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 action and payload before the API reference. Every clause earns its place with no redundancy.

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

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

For a single-parameter read-only getter with no output schema and full annotation coverage, the description is nearly sufficient: the agent knows the input and the notable contents. It could mention error/not-found behavior, but nothing essential to correct invocation 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 there is a single parameter documented as 'The vehicle id.', so the schema carries the semantics. The description's 'by id' adds nothing beyond that; baseline 3 is appropriate.

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

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

States a specific verb (fetch), resource (a single vehicle), and selection key (by id), plus the notable extra payload (mileage and tire-pressure logs). This clearly distinguishes it from shopmonkey_create_vehicle and shopmonkey_list_customer_vehicles 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?

Usage is only implied: the tool requires a vehicleId, so an agent infers it is used when an id is already known. There is no explicit guidance about when to prefer this over shopmonkey_list_customer_vehicles when starting from a customer, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context the annotations do not: the underlying endpoint (GET /v3/canned_service) and the shape of what comes back (labor, parts, fees, total in cents). It does not mention pagination behavior or result limits, which is the remaining gap.

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

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

Two tight sentences with the object definition front-loaded and no filler; the endpoint citation is a small but legitimate addition for developers. No sentence is wasted, though the endpoint reference is marginally redundant for a purely agent-facing definition.

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, two-parameter list tool with no output schema, the description covers purpose, returned fields, and unit (cents). Not stating whether the response is paginated or how many records come back is a minor omission, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, with both skip and limit fully documented in the schema, so the baseline is 3. The description adds nothing about parameter semantics beyond what the schema already states.

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 shop's canned services') and immediately defines the domain concept as 'reusable job templates like Oil change', so an agent unfamiliar with Shopmonkey terminology still understands the object. It also names the returned content (labor, parts, fees, total in cents), distinguishing it from order/customer list siblings.

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

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

Usage is only implied: an agent can infer this is the discovery call for available service templates, but the description never states when to reach for it (e.g. before building an order or estimate) or what it is not for. No sibling conflicts exist, so the gap is moderate rather than severe.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context by defining what the returned orders comprise (estimates, repair orders, invoices) and exposing the underlying endpoint, but it says nothing about pagination behavior, result size, or empty-result handling despite skip/limit parameters.

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 purpose and elaborated with a parenthetical. No wasted words; the endpoint reference is compact and appended last.

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-resource list tool with full schema coverage and no output schema, the description is nearly sufficient. The only gap is that pagination semantics are left entirely to the schema rather than being summarized.

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, so the baseline is 3. The description adds no additional parameter meaning (e.g., default page size or the effect of omitting limit) beyond the structured fields.

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 (a customer's work orders) and clarifies the resource by enumerating what an order can be (estimates, repair orders, invoices). The customer-scoped framing distinguishes it from the workspace-wide shopmonkey_list_orders, but no sibling is named explicitly.

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

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

The phrase 'their service history' implies the use case (retrieving a customer's past work), but there is no explicit when-to-use, when-not-to-use, or routing to shopmonkey_list_orders / shopmonkey_get_order. Usage is only implied.

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

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

readOnlyHint=true already tells the agent this is a safe non-mutating read. The description adds the underlying REST endpoint (GET /v3/customer/:id/vehicle) and the shape of the returned record, which is useful since no output schema exists, but it says nothing about 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?

A single front-loaded sentence plus the endpoint reference; nothing is wasted. It is perhaps overly terse, folding the endpoint into the same line, but every element 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 read-only list tool with annotations covering safety and a 100%-documented schema, the description is nearly sufficient: it conveys the resource, the owning customer, and the returned fields even though there is no output schema. Only pagination semantics and sibling routing are missing.

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

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

Schema description coverage is 100%, so customerId, skip and limit are already documented in the schema. The description adds no parameter meaning beyond that (the listed fields describe the response, not the inputs), so the baseline of 3 applies.

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

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

States a specific verb ('List') and resource ('vehicles owned by a customer') and enumerates the returned attributes (year/make/model, VIN, plate, mileage). It is distinguishable from the singular shopmonkey_get_vehicle and from list_customer_orders, though it never names those siblings explicitly.

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

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

Usage is only implied by the phrase 'owned by a customer' plus the required customerId. There is no statement of when to prefer this over shopmonkey_get_vehicle or shopmonkey_list_customer_orders, and no note that results may be paginated through skip/limit.

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 useful payload context (what fields each order carries, totals in cents) and the backing endpoint, but says nothing about defaults, page-size limits, or the ordering of results. Adequate but not rich behavioral disclosure.

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

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

Three tight sentences: purpose and paging first, then the return payload, then the sibling routing. Every sentence carries information and nothing is repeated from structured fields.

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

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

With no output schema, the description compensates by enumerating the order fields (number, status flags, totals in cents, workflow status, technicians), which is genuinely helpful. The only gap is pagination defaults (no stated default limit or ordering), which matters for a paged list tool.

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

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

Schema coverage is 100% and both parameters are fully documented there, including their roles in paging. The description's 'paged' adds only a hint that skip/limit apply; it contributes no syntax, defaults, or max-limit guidance beyond the schema, so the baseline of 3 is correct.

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

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

States a specific verb and resource ('List work orders for the shop') plus a scoping qualifier ('paged'), and explicitly separates itself from shopmonkey_list_customer_orders. An agent can distinguish this from get_order or list_customer_orders without opening a schema.

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

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

Names the alternative tool (shopmonkey_list_customer_orders) and the condition that selects it ('for one customer's orders'), which is exactly the decision point an agent faces between these two siblings. It also flags the paging pattern via skip/limit.

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 already covering the safety profile, the description adds valuable behavioral context by enumerating the returned data (line items, authorization status, totals). It stops short of describing pagination or response shape, which keeps it from a 5.

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

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

The description is a single front-loaded sentence followed by a compact endpoint reference. Every phrase contributes to understanding what is returned, with no filler.

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

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

For a simple read-only list tool with one well-documented parameter and no output schema, the description covers the essential return content. However, it omits any mention of pagination or result limits, which would be useful for a list endpoint.

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 input schema has 100% description coverage for the single orderId parameter, so the schema already documents it. The description adds no parameter syntax or format details beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb ('List') and resource ('services (jobs) on a work order'), and details the included line items and totals, making it clearly distinct from sibling list tools like list_orders or list_canned_services.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The description merely states what the tool does; an agent must infer from the purpose that this is the right tool for retrieving an order's services.

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 nature is covered. The description adds the fact that returned ids are consumed by other operations, which is useful behavioral context, but says nothing about pagination behavior, result size limits, or scope beyond the schema's skip/limit.

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

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

A single compact sentence front-loads the resource and then the applicable user types. The trailing endpoint string ('Shopmonkey: GET /v3/user') is minor but largely redundant for an agent selecting a tool.

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

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

For a read-only list tool with full schema coverage on both params and annotations covering safety, the description supplies what an agent needs: what is listed, the subtypes, and why the ids matter. Only the pagination/return-shape context is absent, which is acceptable without 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 both parameters (skip, limit) are already documented in the schema. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (the shop's users), and enumerates the user categories returned (service writers, technicians, admins). The added note that these are 'the ids to use for technicians and service writers' clarifies the downstream purpose, though it doesn't name a sibling to contrast against.

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

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

Usage is implied rather than stated: the parenthetical about ids for technicians/service writers hints at why an agent would call it (to populate those fields elsewhere), but there is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

readOnlyHint=true already establishes the read-only safety profile, so the bar is lower. The description adds that results are ordered/positioned board columns and that the returned ids feed update_order, which is genuinely useful, but it says nothing about paging behavior or result volume beyond what the skip/limit params 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?

Three tight sentences: purpose first, then the practical linkage to update_order, then the underlying endpoint. Every sentence carries information and nothing is padded.

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

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

With no output schema, the description compensates by describing what a returned status contains (an id and a position), which is the essential shape. Pagination semantics are left entirely to the schema, and there is no note on default limits, so it is strong but not exhaustive.

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 and limit fully documented in the schema, so the baseline is 3. The description adds no additional parameter meaning, which is acceptable here since it has no need to compensate.

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

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

Specific verb+resource ('List the workflow statuses') with a clarifying gloss that ties the abstract term to the domain model ('the columns of the shop's work-order board'). It also states what each record carries ('with their position'), so an agent can distinguish it from generic list siblings without opening a schema.

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

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

Explicitly links this tool to a downstream action: 'Use the id to move an order with shopmonkey_update_order,' which tells the agent why it would call this list first. It gives clear context but no exclusions or alternative-list routing, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered structurally. The description adds that results include the related customer and names the underlying endpoint, but says nothing about defaults, result caps, or paging interaction for an 11-parameter query.

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 purpose front-loaded. The trailing 'Shopmonkey: POST /v3/appointment/search' endpoint notation adds little for an agent choosing a tool, keeping it short of a 5.

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

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

No output schema exists, and the description does supply the key return shape (appointments with their customer), while the schema fully covers filters. The remaining gap, default behavior when no filters are supplied and result paging limits, is minor but real.

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 including skip/limit/sort breathing room is already documented. The description's list of filter dimensions merely restates parameters the schema defines more precisely; 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 ('Search') and resource ('the appointment calendar'), then names the filter dimensions (date range, customer, order, technician) and the return content ('appointments with their customer'). That is enough to separate it from shopmonkey_create_appointment and shopmonkey_search_customers 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?

The description gives no when-to-use or when-not-to-use guidance relative to siblings such as shopmonkey_list_orders or shopmonkey_search_customers, and no prerequisites or paging advice. Usage is only implied by the word 'Search' and the listed filters.

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 that the search is server-side and that results carry emails and phone numbers, which is meaningful behavioral context for a read tool with no output schema.

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

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

Two short sentences, front-loaded with the verb and the filter/sort/paging capabilities. The trailing "Shopmonkey: POST /v3/customer/search" endpoint note is mildly redundant but not 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?

With no output schema, the description usefully states what is returned (customers with emails and phone numbers), and the schema fully documents paging and filtering. An agent has enough to call it correctly, though tool-selection guidance relative to siblings is the remaining 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 each of the four parameters (skip, limit, where, orderBy) has an example-bearing description, so the schema does the heavy lifting. The description adds nothing about parameter syntax, making the baseline 3 appropriate.

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

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

States a specific verb+resource ("Search customers") and qualifies it with server-side filter, sort and paging, which separates it from the narrower find_customers_by_email/phone siblings. It does not, however, explicitly name those siblings to route the agent.

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 mention of a server-side filter implies this is the general-purpose lookup tool, but no when-to-use/when-not guidance is given against the many alternatives (find_customers_by_email, find_customers_by_phone, get_customer, list_customer_orders). Usage must be inferred.

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

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

With readOnlyHint=true the safety profile is already covered by annotations, so the description only needs to add context. It contributes the field inventory and the units of monetary fields ("retail and wholesale cost in cents") along with the underlying endpoint POST /v3/inventory_part/search, which is useful. It says nothing about result volume, pagination behavior, or default result set size.

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

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

One front-loaded sentence stating the resource and its fields, followed by a filter example and the endpoint reference. Every element is relevant, though the field enumeration is a long run-on list that could have been trimmed given the schema carries the parameter details.

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 optional-parameter search tool with no output schema and read-only annotations, the description covers what is searchable, the filter shape, and the backing endpoint. It does not describe the response envelope or pagination semantics indirectly, but the schema's skip/limit descriptions largely fill that gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description supplies a filter example ({"sku": "ABC-123"}) that illustrates the intent of the `where` object, but it never maps that example to a named parameter and does not explain `skip`, `limit`, or `orderBy`, which the schema already documents.

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 verb and resource ("Search the parts inventory") and enumerates the searchable/returnable fields (SKU, part number, bin location, costs). That is enough for an agent to know exactly which API operation this is. There is no competing inventory sibling in the tool list, so sibling differentiation is trivially satisfied rather than explicitly demonstrated.

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 shows a filter example ({"sku": "ABC-123"}) but never says when to use this tool versus the many customer/order/appointment siblings, nor when it would be the wrong choice. There is no mention of prerequisites, required identifiers, or scope limits such as whether it searches all inventory or a single location.

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?

Beyond the destructiveHint annotation, the description discloses meaningful partial-update semantics ('Only the fields you pass are sent'), which matters because the underlying verb is PUT and would otherwise suggest full replacement. It still does not explain what makes the call destructive, whether changes are reversible, or error behavior for an unknown customerId.

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 resource and action, and the partial-update rule is stated immediately after. The trailing 'Shopmonkey: PUT /v3/customer/:id' is marginally useful metadata rather than wasted space.

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

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

For a 17-parameter mutation with no output schema, the definition covers the core mutation contract but omits return behavior, validation failure handling, and permission/auth requirements. Annotations cover only the destructive flag, so the description leaves real gaps for a write operation.

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 all 17 parameters, so the schema already documents every field, including the two enums and the country-code pattern. The description's field summary ('name, address, note or preferences') only loosely groups what the schema lists, 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 ('Update a customer') and enumerates the field groups affected (name, address, note, preferences). It does not explicitly distinguish itself from sibling mutations like shopmonkey_update_order, but the resource identity is unambiguous.

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

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

Usage is only implied: the agent infers this is for modifying an existing customer versus shopmonkey_create_customer. There is no explicit when-to-use condition, no prerequisite statement (e.g., customerId must already exist), and no routing away from alternatives such as shopmonkey_add_customer_email.

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 already flags this as a mutating call, and the description usefully adds the partial-update contract ("Only the fields you pass are sent"), which is not in the annotations. However, it does not explain what archive does to the order, whether changes are reversible, or any permission requirements — meaningful gaps for a destructive operation.

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 dense sentences, front-loaded with the operation and its editable surface, with no filler. Minor redundancy in repeating the Estimate/RepairOrder/Invoice enum values already defined in the schema, and the trailing API path adds only marginal 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 12-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers the operation's scope and partial-update semantics well, and the schema carries the per-field detail. Missing only edge behaviors (archive effects, failure modes) that an agent would want before archiving a work order.

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 12 parameters is already documented in the schema, including the status enum and the workflowStatusId cross-reference. The description restates a subset of fields but adds no format, syntax, or constraint detail beyond what the schema provides; 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 ("Update a work order") and then enumerates exactly which aspects can be changed: workflow status, status, complaint/recommendation, due date, service writer, or archive. This is clearly distinguishable from sibling tools like shopmonkey_create_order or shopmonkey_update_customer 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?

Usage is implied (modify an existing order) and "Only the fields you pass are sent" signals partial-update behavior, but there is no explicit when-to-use vs. when-not guidance and no named alternatives (e.g. use shopmonkey_get_order first, or create_order for new work). Adequate but leaves routing to inference.

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