kickserv

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

Annotations only declare destructiveHint=true; the description adds that this is a write and explains the customer-visible effect of `public`. It does not state auth/permission requirements, whether the note can be edited or removed, or what a successful call returns, so it partially compensates for thin annotations but leaves real gaps.

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 operation and mutation type, with no filler. The trailing endpoint string adds minor debugging value but is arguably redundant, keeping it just short of a 5.

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

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

For a simple 3-parameter write tool with full schema coverage and no output schema, the description covers purpose, mutation nature, and the key visibility flag. The main omission is any notion of the return value or confirmation of success, which is acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description's explanation of `public` merely restates the schema text. Baseline 3 is appropriate since the schema carries the parameter burden.

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 a note to a customer') and the WRITE prefix immediately signals a mutation. The 'customer' resource clearly differentiates it from the sibling kickserv_add_job_note, so an agent can route correctly 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?

No when-to-use, when-not-to-use, or alternative guidance is given. The WRITE label implies a mutation context, but nothing tells the agent when to choose this over kickserv_add_job_note or how it relates to kickserv_list_customer_notes.

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?

Goes beyond the destructiveHint annotation by explaining the financial consequence ('changes the job's estimate/invoice total') and, critically, the limitation that it does NOT charge the customer's card — a distinction that prevents a costly misread. The raw POST endpoint adds traceability, though auth and error behavior are unstated.

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

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

Three tight sentences, front-loaded with the write classification, then consequence, then input source, then endpoint. Every clause carries information; nothing is padding.

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

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

For an 8-parameter mutation with a fully documented schema and no output schema, the description covers effect, non-effect, and input sourcing adequately. Remaining gaps (permissions needed, behavior on invalid item_id) are minor given the rich 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 coverage is 100%, so the primary semantics for quantity, price_per_unit, discount, and details already live in the schema. The description reinforces the item_id provenance, but adds little meaning beyond what the schema states, 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 ('add a charge (line item) to a job') with the 'WRITE:' prefix making the operation class explicit. It clarifies the resource taxonomy (product, service, or part) so the agent knows exactly what object is created.

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?

Points the agent to the sibling tool kickserv_list_items for obtaining item_id, which is real routing guidance. It does not, however, state when to prefer this over the note-adding or job-update siblings, so exclusions are only partial.

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; the description adds the mutation framing ('WRITE') and the endpoint (POST /jobs/{job_number}/notes.xml), plus the customer-visibility semantics of `public`. It does not cover auth/permission requirements or what the call returns, and it never reconciles why a note append carries a destructive hint.

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 plus an endpoint, with the operation type front-loaded in 'WRITE:'. Nothing is padded, though the raw endpoint string is the least valuable element for an agent choosing or calling 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 3-parameter mutation with no output schema and sparse annotations, the description covers the core action and the one non-obvious flag. It leaves the return value (e.g., new note ID) and any permission constraints unaddressed, which is adequate but not complete.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the customer-visible meaning of `public`. The description restates the `public` semantics rather than adding new information, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('WRITE: add a note to a job'), which distinguishes it from the read-side sibling kickserv_list_job_notes. Differentiation from kickserv_add_customer_note is implicit in the object ('a job') rather than stated, so it stops just short of a 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?

Usage is implied by the WRITE label and the object of the note, but there is no explicit when-to-use/when-not or reference to alternatives such as kickserv_add_customer_note. The `public` flag guidance is useful but is about a parameter, not about selecting this 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 flag destructiveHint=true, so the write nature is covered structurally. The description adds value by stating the server assigns the customer number (so the agent should not supply it) and that it is a POST, but says nothing about permissions, idempotency, duplicate handling, or what is returned.

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 fragments, front-loaded with the write marker and the key behavior (server-assigned number). The trailing endpoint string is mild implementation detail but harmless.

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

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

For a 31-parameter creation tool with no output schema, the description is thin: it doesn't state what a successful call returns (e.g., new customer id) or note that most fields are optional. Schema coverage compensates for field meaning, but the response contract is unaddressed.

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

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

Schema description coverage is 100% across all 31 parameters, so the schema carries the documentation burden and the baseline of 3 applies. The description itself contributes no parameter-level detail beyond noting the customer number is server-assigned.

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

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

The description gives a specific verb and resource ('create a new customer') and adds that Kickserv assigns the customer number. It is clearly distinct from sibling tools like kickserv_create_job or kickserv_update_customer, though it never explicitly contrasts itself with any of 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?

There is no guidance on when to use this versus alternatives such as kickserv_update_customer (for existing records) or kickserv_get_customer. No prerequisites, no mention that only 'name' is required.

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 annotation only declares destructiveHint=true; the description adds real behavioral context by labeling this a WRITE, flagging the internal-id vs customer-number pitfall, and disclosing the underlying POST endpoint. It still omits whether the response returns a new job id, permission requirements, or duplicate-handling 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 WRITE verb and the tool's purpose, with no filler. Slight redundancy with the schema descriptions on customer_id/job_type_id keeps it from a 5.

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

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

For a 10-parameter create tool with no output schema, the description covers purpose and ID sourcing but omits auth/permission expectations and any mention of what is returned (e.g. the new job id). It is workable but leaves an agent guessing about the post-call workflow.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters, and the description's notes on customer_id, job_type_id, and estimate largely restate the schema descriptions. The endpooint reference is the only genuinely additive detail, so baseline 3 is right.

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

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

The description opens with a precise verb+resource ("create a job (work order) for a customer") and clarifies the domain term (work order). It also names the sibling used to source a required ID (kickserv_get_customer), which lets an agent distinguish it from read/update siblings at a glance.

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 explains how to source the required IDs and what the `estimate` flag does, which is useful context. However, it gives no explicit when-to-use or when-not-to-use guidance (e.g. vs kickserv_create_task or kickserv_update_job), leaving the routing decision to inference.

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 provide destructiveHint=true, and the description's 'WRITE:' prefix is consistent with that rather than merely repeating it. It adds the useful disambiguation that job_id is the internal id, not the job number, but discloses nothing about side effects such as notifications to assigned employees, permission requirements, or reversibility of the assignment replacement.

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 operating mode, resource, scope, ID provenance, and the underlying endpoint all front-loaded and no filler. Every clause earns its place.

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

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

For a 9-parameter mutation with no output schema and only a destructiveHint annotation, the description covers ID sourcing and write-mode but omits what the call returns (presumably a task id needed for later kickserv_get_task/update calls) and how the three time-related parameters relate. Adequate but leaving real 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% and the schema already documents every parameter, including the job_number caveat that the description restates. The description adds no meaning about how scheduled_at, ends_at, and duration interact, so with the schema doing all the work, 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?

The description names a specific verb and resource ('create a task (appointment / to-do) on a job') and adds scope ('optionally assign employees'), plus the WRITE prefix. An agent can distinguish it from kickserv_create_job, kickserv_create_customer, and kickserv_get_task 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?

It routes the agent to the correct source for the two non-obvious IDs (job_id from kickserv_get_job, employee_ids from kickserv_list_employees), which is exactly the context needed before calling. It stops short of explicit when-not guidance or stating what to do if the job has no tasks (e.g. create_job instead).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lighter. It adds genuinely useful behavioral context beyond the annotation: the returned `id` is the key consumed by job/task creation calls, which is the main reason to call this tool. It does not discuss missing-customer behavior 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?

Two sentences, both front-loaded: the core fetch semantics first, then the downstream id linkage. No filler, and the raw HTTP endpoint is appended compactly at the end.

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 compensates by telling the agent the salient return field (`id`) and its purpose. Combined with the readOnly annotation and 100% schema coverage, an agent has enough to call this correctly; only edge-case behavior (not-found handling) is unaddressed.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, setting the baseline at 3. The description restates four of the six `include` enum values (contacts, jobs, tasks, notes) but omits tax_entity and custom_field_assignments, adding no new syntax or semantics 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 one customer by customer number') and scopes it to a single record, which cleanly separates it from the sibling list_customers. The optional include set is named, so an agent knows the shape of the call before opening the schema.

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

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

Gives a concrete downstream usage rule: the result's `id` is what job/task create calls need as `customer_id`. That is real routing guidance. It does not, however, explicitly say when to prefer this over list_customers or how it relates to update_customer, so it stops short of full when/when-not coverage.

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

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

The readOnlyHint=true annotation already establishes this is a safe read. The description adds the API route and the fact that related entities can be embedded, which is mildly useful, but says nothing about pagination, auth, or error behavior.

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

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

Two compact sentences with the core action front-loaded and the embed options following. The trailing REST endpoint reference is dispensable but short enough not to harm readability.

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 partially compensates by naming the entities that can be returned via embeds, which tells an agent what a response may contain. Still, it omits any statement of what the base response looks like when no embeds are requested.

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 job_number and include are already fully documented in the schema. The description's list of embeddable resources merely restates the enum values, adding no 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 ('Fetch one job by job number') and scopes it to a single record, clearly distinguishing it from the plural sibling kickserv_list_jobs. The enumeration of optional related data further pins down what the call returns.

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 'one job' vs list distinction, but there is no explicit when-to-use statement, no guidance on when to request embeds vs calling the dedicated list_* tools (e.g. list_job_notes), and no prerequisites mentioned.

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 annotation readOnlyHint=true already establishes that this is a safe read operation. The description adds useful context by identifying the underlying Kickserv endpoint and clarifying what a task represents, but it does not disclose error behavior, authentication requirements, or response details.

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 two short sentences, front-loaded with the tool's purpose and followed by the concrete endpoint. Every element earns its place without repetition or 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 get-by-id tool with complete parameter documentation and a readOnlyHint annotation, the description supplies the needed domain context. It is nearly complete, though it could mention return format or error cases, which is a minor gap 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 single task_id parameter is fully documented in the schema. The description adds only 'by id,' which does not meaningfully extend the schema's meaning, making the baseline of 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?

The description states a specific verb and resource: fetch one task by id. It also clarifies that a task is an appointment or to-do attached to a job, which helps distinguish it from job- or customer-level tools. It does not explicitly name alternatives among siblings, so it falls short of a 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 'by id' implies usage: call this when you have a task_id and need the corresponding task. However, there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance, so the usage context remains 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?

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral detail beyond them: the 30-records-per-page pagination behavior and the underlying GET endpoint. It still doesn't describe ordering or response shape, but pagination is the key operational fact for iterating results.

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 and pagination front-loaded and no filler. Every clause carries information the agent needs.

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-page list tool with full schema coverage and no output schema, the definition supplies the essentials (scope, page size, endpoint). A note on default ordering or total counts would make it fully complete, but nothing required 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?

With 100% schema description coverage, the schema already documents only/page/include/customer_number, and the page description itself repeats the 30-per-page note. The description adds no semantics beyond what the structured schema provides, 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 (jobs) scoped to 'one customer', which separates it from the broad kickserv_list_jobs sibling. It is clear what the tool returns, though it never names the sibling explicitly to reinforce the distinction.

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 'for one customer' scope; there is no explicit when-to-use, when-not-to-use, or alternative routing. An agent can infer it, but the definition leaves the choice between this and kickserv_list_jobs to inference.

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 by structured data. The description adds only the REST endpoint string, disclosing nothing behavioral beyond it — no pagination, ordering, or note-visibility semantics for a list 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 compact sentences, zero filler, with the core purpose front-loaded before the incidental API endpoint reference. Nothing could be removed without losing 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 simple one-parameter read tool whose annotations carry the safety profile, this is adequate but thin: with no output schema, the description says nothing about what the returned notes look like or whether results are paginated/sorted.

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

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

Schema coverage is 100% and the single parameter (customer_number) is fully documented in the schema. The phrase 'on one customer' implies the customer scope but adds no format or meaning beyond what the schema already 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 and resource ('List the notes on one customer'), and the customer-scoped framing distinguishes it from the job-note sibling kickserv_list_job_notes. It is clear, though it never names an alternative explicitly, so sibling differentiation is left 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?

There is no when-to-use or when-not-to-use guidance, no mention of alternative tools (kickserv_get_customer, kickserv_list_job_notes, kickserv_add_customer_note), and no prerequisites. Usage is only inferable from the tool name.

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

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

Annotations already cover the safety profile (readOnlyHint=true), yet the description adds real behavioral context: a 30-per-page pagination size, the fact that every filter is an exact match, and the response-size benefit of `only`. It stops short of stating total-count behavior or the 10,000-page cap, so it is not exhaustive, but it meaningfully exceeds the annotations.

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

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

Four tight sentences, front-loaded with the core purpose and pagination fact before the tips. Every sentence carries signal; only the trailing endpoint reference ('GET /{account}/customers.xml') is mildly redundant for an agent, preventing 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?

With no output schema and 12 optional params, the description supplies the essentials an agent needs: collection intent, page size, exact-match filtering, and a response-slimming lever. Acceptable embedding details like `include` are left to the schema, which is reasonable given its full coverage.

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 baseline is 3, but the description goes slightly beyond the per-field docs by generalizing 'Every filter is an exact match on that field' across all 12 params and explaining the payoff of `only`. This reinforces semantics the individual schema blurbs state piecemeal.

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 opens with a specific verb+resource, 'List or search customers', which clearly indicates a collection read vs. a single-record read. However, it never names the distinguishing sibling (kickserv_get_customer for a single lookup), so the differentiation from siblings is only implied by the plural noun.

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

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

It offers one concrete usage tip ('Use `only` to keep the response small') and states that filters are exact matches, which is operationally useful. But it never says when to reach for this tool instead of kickserv_get_customer or kickserv_list_customer_jobs, and gives no exclusions or prerequisites, leaving most routing to inference.

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 already signals a safe read, and the description adds real value beyond it by disclosing that both active and inactive employees are returned and by naming the raw endpoint (GET /{account}/employees.xml). It stops short of describing pagination or result-size behavior.

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

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

Two tight sentences with zero filler. The scope of the listing is front-loaded, followed by field-usage guidance, then the endpoint.

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 hinting at the return shape, and it does so by naming the two key fields and the active/inactive range. Missing only pagination/ordering behavior, a minor gap for a no-arg 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?

The tool takes zero parameters, so the baseline is 4. The field names mentioned (`id`, `employee_number`) are output fields rather than inputs, so there is no parameter semantics to clarify.

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 all employees') and immediately scopes it ('technicians and office staff, active and inactive'), so an agent knows exactly what population is returned. No employee-listing sibling exists to confuse it with, and the underlying endpoint 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?

Explains the downstream purpose clearly: use `id` for job/task assignment and time entries, `employee_number` to filter jobs. That tells the agent when this tool is the right prerequisite step, though it never states an explicit when-not or names an 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description's additional facts (30 per page, active-by-default, XML endpoint) largely restate what the input schema already documents for `page` and `which`, so marginal behavioral value is low.

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

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

Three compact sentences, front-loaded with the resource and its domain meaning, then defaults. The trailing 'Kickserv: GET /{account}/items.xml' adds little for an agent choosing a tool, 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?

Zero required parameters, a simple read-only list, and pagination/default-filter behavior all stated — enough to call it correctly. With no output schema, the description could say more about what each listed item contains, but the omission is minor for a catalog list.

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%: name, page, and which are all documented in the schema, including the 30-per-page behavior and the active/inactive/all enum. The description repeats rather than extends that, so the baseline 3 applies.

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

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

States a clear verb (List) and resource (products/services), and adds the disambiguating gloss 'the price list used for job charges' so the agent knows 'items' means billable catalog entries. No sibling tool overlaps this resource, so explicit sibling differentiation isn't needed, but none is offered either.

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?

'Active items only by default' implies the common case and hints that the `which` parameter changes it, which is implied usage guidance. It never states when to reach for this tool versus e.g. kickserv_list_customers or job lists, nor any 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?

The readOnlyHint annotation already establishes this as a safe read, lowering the burden. The description adds the underlying endpoint (GET .../notes.xml), which usefully signals an XML response, but it says nothing about pagination, volume, or 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?

Two short sentences, front-loaded with the purpose before the API detail. The endpoint sentence is arguably redundant but does carry format information, so it 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 one-parameter read-only listing tool with annotations covering safety, this is largely complete, and the .xml hint partly compensates for the absent output schema. Return shape and pagination behavior remain undocumented.

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

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

With a single parameter at 100% schema description coverage, the schema already documents job_number fully. The description's 'one job' confirms the identifier but adds no syntax, range, or lookup 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 states a specific verb ('List') and resource ('the notes on one job'), scoping the operation to a single job. It is distinguishable from kickserv_add_job_note (write) and kickserv_list_customer_notes (different owner), though it never names those siblings to sharpen the distinction.

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

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

There is no guidance on when to use this versus kickserv_list_customer_notes or other listing tools, and no stated prerequisites or exclusions. Usage is only implied by the phrase 'notes on one job'.

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 establish readOnlyHint=true, so the safety profile is covered; the description adds the 30-records-per-page limit and the underlying GET /{account}/jobs.xml endpoint, which is useful operational context. It stops short of disclosing anything about rate limits, auth, or 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 dense sentence that front-loads the verb and resource, then pagination, then filters, with the endpoint appended. No wasted words.

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

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

For an 8-parameter read-only list tool with no output schema, the description covers pagination and the main filter axes, and annotations cover safety. It is slightly incomplete in not flagging the response-shaping 'only'/'include' options, but those are fully described in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the description echoes the filter dimensions (schedule window, status, employee, category, job status) but adds no syntax, defaults, or semantics beyond what the schema already documents, and omits mention of the 'only' and 'include' parameters that strongly shape responses.

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 jobs') and clarifies the resource spans work orders, estimates, and invoices. It also names the filters and pagination, but does not distinguish itself from the close sibling kickserv_list_customer_jobs or from get_job.

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 listed filters (schedule window, status, employee, category, job status) imply the intended use for browsing/filtering jobs, but there is no explicit when-to-use, when-not, or pointer to alternatives such as list_customer_jobs for a single customer's jobs.

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 non-destructive read, so the description's burden is reduced. It adds the underlying REST call (GET /{account}/jobs/{job_number}/time_entries.xml), but says nothing about pagination, result volume, or whether an empty list is possible when no hours are logged.

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

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

Two short sentences, zero filler, with the primary action and scope front-loaded before the endpoint detail. Every clause earns its place.

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

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

For a one-parameter read tool with no output schema, the description covers purpose, scope, and the backing endpoint adequately; the parenthetical also conveys what the returned entries represent. It stops short of noting result shape or limits, which keeps it from a 5.

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

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

With a single parameter and 100% schema description coverage, the schema already documents 'job_number' fully, so baseline 3 applies. The description only hints at the parameter indirectly through the endpoint path and adds no new semantics such as format or constraints.

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

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

The description names a specific verb and resource ('List the time entries') and scopes it to 'one job', with a parenthetical defining what a time entry is ('hours logged by technicians'). That definition naturally separates it from sibling listing tools such as kickserv_list_job_notes.

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 can infer you call this to read a job's logged hours, but there is no statement of when to prefer it over alternatives (e.g., kickserv_log_time_entry for writes) and no exclusions or prerequisites. Adequate but with a clear gap.

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 and the description mostly restates that with 'WRITE' plus the POST endpoint. It does not disclose what the write affects downstream (billing totals, job hours) or whether entries can be edited/deleted after creation, so it adds only modest context beyond annotations.

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

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

Two short sentences, front-loaded with the WRITE classification and the core action, with the lookup hint and endpoint following. 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 9-parameter write with no output schema and only a destructiveHint annotation, the description covers the essentials of what it does but omits side effects and defaults (e.g., billable default, time_entry_type_id optionality impact). Adequate but with clear gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine cross-tool fact: employee_id comes from kickserv_list_employees. That is meaning the schema does not provide, which lifts it above 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: 'log hours worked by an employee on a job', and prefixes it with 'WRITE'. An agent can immediately distinguish this mutation from read siblings such as kickserv_list_job_time_entries.

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 WRITE framing and the employee_id pointer to kickserv_list_employees, but there is no explicit when-to-use/when-not guidance and no mention of alternatives (e.g., updating vs creating a time entry).

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 adds that this is a partial PATCH (untouched fields are preserved) and enumerates the field classes that cannot be mutated here. It does not mention permission/auth requirements, rate limits, or error behavior, but it goes meaningfully beyond the structured annotations.

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

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

Three short sentences, front-loaded with the mutation class ('WRITE:'), then the update semantics, then the exclusions, then the endpoint mapping. Every sentence carries distinct information with no restatement of the name or title.

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

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

For a 32-parameter mutation tool with full schema coverage and only a destructiveHint annotation, the description covers the essentials: operation type, partial-update behavior, and scope limits. It omits what the call returns (no output schema exists) and any failure/permission notes, which keeps it short of fully complete.

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

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

Schema coverage is 100% (32 params, all documented), so the baseline is 3. The description still adds semantics the schema cannot express: that omitted parameters are left unchanged (partial-update contract) and that balances, credit limit, and custom fields are out of scope for this 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 specific verb and resource ('WRITE: update fields on an existing customer') and pins the semantics as a partial update via 'Only the fields you pass change'. The 'existing customer' framing cleanly separates it from create_customer and get_customer among the siblings without needing to name 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?

Gives clear usage context ('only the fields you pass change') and an explicit exclusion set ('Balances, credit limit and custom fields are not settable here'), which tells the agent when this tool will not work. It stops short of naming the correct alternative for those excluded fields, so it lacks the explicit routing a 5 would require.

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 provide only destructiveHint=true, so the description carries most of the burden and delivers: the WRITE prefix, the fact that employee_ids replaces the existing assignment (destructive overwrite), the exclusion of totals/tax/payment, and the underlying PATCH endpoint. It omits permission requirements and whether omitted fields are preserved.

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 the WRITE signal, the mutable-field list follows immediately, and the endpoint string is tucked at the end. No filler and nothing repeated from 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 10-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers scope, exclusions and the destructive employee-reassignment behavior. It leaves unstated whether the PATCH is partial/merge semantics and what error behavior to expect for an invalid job_number.

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 still adds value by mapping fields to business concepts (job_type_id = category, job_status_id = custom job status) and by explicitly stating which parameter space is absent (totals, tax, payment). The 'replaces the assignment' note duplicates the schema text, so it earns 4 rather than 5.

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

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

States a specific verb (update) plus the resource (an existing job) and enumerates the mutable surface: reschedule, rename, description, category, custom job status, employee reassignment. That enumeration cleanly separates it from kickserv_create_job and kickserv_get_job 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 line 'Totals, tax and payment fields are not settable here' implicitly routes charge/money edits elsewhere (e.g. kickserv_add_job_charge) and prevents wasted calls, which is real usage guidance. It does not, however, name an alternative tool explicitly or state when-not-to-use conditions such as a missing job_number.

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