Kickserv MCP by usefulapi

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

The annotation only supplies destructiveHint=true, so the description does add real context: it marks the operation as a write and explains that `public` controls customer visibility, a privacy-relevant consequence. It still omits auth requirements, whether the note can later be edited/removed, and why an additive operation is flagged destructive.

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, mutation intent front-loaded, no padding. The REST endpoint ('POST /{account}/customers/{customer_number}/notes.xml') is marginally useful for debugging but borders on redundant with the tool name.

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

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

For a simple three-parameter write tool with full schema coverage and no output schema, the description covers purpose, the one non-obvious flag, and the endpoint. Only auth/permission context and the note lifecycle are missing, which is minor at this 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 coverage is 100%, so all three parameters are already documented in the schema. The description's restatement of the `public` flag ('visible to the customer') duplicates the schema text rather than adding format, default, or edge-case detail. Baseline 3 applies 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+resource ('add a note to a customer') and prefixes it with 'WRITE', so the mutation intent is unmistakable. It does not, however, explicitly distinguish itself from the sibling kickserv_add_job_note, leaving the agent to infer the target-object difference.

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

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

There is no when-to-use guidance, no mention of the sibling add_job_note alternative, and no prerequisites (e.g. that the customer must exist). The agent must infer usage purely from the name and the 'WRITE' prefix.

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, so the description must add the operational context, and it does: it discloses that the job's estimate/invoice total is mutated and that no card is charged, plus the underlying endpoint. It omits permission/auth requirements and whether the added charge can be removed afterward.

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 WRITE marker and the core action, with the disambiguation and the sourcing hint following in priority order. 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 an 8-parameter mutation with no output schema, the description covers the write semantics and the item lookup, which is the main ambiguity. The remaining gap is `job_charge_type_id`: it is required but the description gives no hint where its values come from (and there is no list_job_charge_types sibling).

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 schema already says `item_id` comes from kickserv_list_items, so the description repeats structured data rather than adding to it. It adds nothing about `job_charge_type_id`, the other required field, or how quantity/price_per_unit/discount interact.

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

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

States a specific verb ('add'), resource ('charge'), and disambiguates the term with a parenthetical ('line item — a product, service or part'), so the agent knows exactly what is being created on a job. The 'WRITE:' prefix immediately separates it from the read/list siblings and from the note-adding tools.

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

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

It gives a concrete sourcing instruction ('Pick `item_id` from kickserv_list_items') and an explicit exclusion ('does NOT charge the customer's card'), which steers the agent away from a plausible wrong expectation. It stops short of stating when to prefer this over the note-adding siblings or what job state 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?

Annotations provide only destructiveHint=true; the "WRITE:" prefix is consistent with a mutation and confirms the write nature. The customer-visibility effect of `public` is useful behavioral context, but it largely restates the schema, and there is no disclosure of permissions, return payload, or default visibility explicitly.

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

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

Two short sentences with zero filler, front-loaded with the WRITE classification followed by the one parameter that changes behavior. Nothing needs trimming and nothing important is buried.

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

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

For a simple three-parameter mutation this covers the essentials (operation, key parameter behavior, endpoint), but with no output schema the description could say what is returned (e.g., the created note id) and whether the note is private by default. The sparse annotations leave those gaps unfilled.

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 job_number, note, and public are all already documented in the schema, including the min/max length on note. The description's mention of `public` adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("add a note to a job") and prefixes it with "WRITE", so the operation's nature is unambiguous. It also pins the exact API surface (POST /{account}/jobs/{job_number}/notes.xml), making it clearly distinct from kickserv_add_customer_note by resource.

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

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

The description gives one concrete usage rule — set `public` to true for customer visibility — which implies the default is a private/internal note. However, it offers no guidance on when to choose this over kickserv_add_customer_note or kickserv_list_job_notes, and no prerequisites or exclusions.

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

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

Annotations declare destructiveHint=true, so the safety profile is partly structured. The description adds two genuinely useful behavioral facts: it is a write, and the customer number is server-assigned rather than caller-supplied. It says nothing about required permissions, duplicate handling, or what the response contains.

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

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

Three short sentences with the WRITE flag front-loaded, so the critical mutation signal comes first. The trailing 'POST /{account}/customers.xml' endpoint detail is mildly redundant for an agent 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?

For a 31-parameter creation tool with no output schema, the description is thin: it does not note that only name is required, does not mention that the new customer's identifier is returned, and does not address the destructiveHint annotation. The exhaustive schema carries most of the burden, but the description could do more.

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 31 fields are already documented in the schema and the baseline is 3. The description adds no parameter-level meaning (e.g., that only name is required, or which contact/company fields matter), so it neither helps nor harms.

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

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

States a specific verb and resource ('create a new customer') with a clear WRITE marker, so an agent can immediately tell this is the creation counterpart to kickserv_update_customer and kickserv_get_customer. It stops short of explicitly naming which sibling to prefer in ambiguous cases.

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_update_customer or how it relates to kickserv_list_customers, and no prerequisites are stated. The only contextual hint is that Kickserv assigns the customer number, which is useful but not usage guidance.

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

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

Annotations only carry destructiveHint=true, and the 'WRITE' marker plus the raw endpoint are consistent with that. The description adds the meaningful 'estimate' mode behavior (creates the record as an estimate rather than a job) beyond the annotation, but says nothing about auth/permission needs, failure cases, or what happens to fields left unset.

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 and the essential identifier caveat. No filler; even the endpoint line serves as a debugging anchor.

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 creation tool with no output schema, the description never says what the call returns (e.g. the new job's id), which an agent typically needs for follow-up calls to kickserv_add_job_note or kickserv_update_job. Required parameters and the create/update boundary are covered, but the post-call picture is not.

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 already 100%, so baseline is 3. The description earns above baseline by flagging the high-risk id confusion (internal customer `id` vs. customer number) and by pointing to the sibling tool that supplies customer_id, which the schema does not do.

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 ('create a job (work order) for a customer') and marks it WRITE, which cleanly separates it from kickserv_update_job and the various add_* sibling tools. The endpoint (POST /{account}/jobs.xml) confirms the operation unambiguously.

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 concrete prerequisites: customer_id must be the internal id obtained from kickserv_get_customer (explicitly not the customer number), and job_type_id is the job category. It also explains the estimate flag's behavioral effect. It stops short of naming when to prefer this over kickserv_update_job or how to handle a job that already exists.

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 'WRITE:' prefix and the POST endpoint corroborate the destructiveHint=true annotation, but the description does not explain what makes a create destructive, nor does it cover permissions, rate limits, or side effects. With annotations already supplying the write/destructive profile, the added context is modest.

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

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

Three tight sentences, front-loaded with the 'WRITE:' operation type, then scope, then the key identifier caveat. No filler; every clause carries information.

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

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

For a 9-parameter write tool with no output schema, the description covers the action, the key identifier pitfall, and the endpoint, which is nearly everything an agent needs to call it. It omits what the call returns (e.g. the new task id), which would be useful given no output schema.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the important `job_id` vs job_number distinction. The description's restatement of that distinction adds no meaning beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource ('create a task') with the resource disambiguated ('appointment / to-do') and scoped ('on a job and optionally assign employees'). An agent can immediately distinguish it from kickserv_get_task and kickserv_update_job 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?

States the create context and points to kickserv_get_job as the source for `job_id`, giving clear provenance guidance. It lacks explicit when-not-to-use guidance or a named alternative for related operations (e.g. logging time entries), 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 safety profile is covered. The description adds genuine behavioral context beyond that: the `include` expansions available and the fact that the returned `id` must be reused as `customer_id` in create calls — a non-obvious contract not visible in 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?

Two sentences, front-loaded with what is fetched and how, followed by the downstream id contract and endpoint. No filler; every clause carries information.

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

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

No output schema exists, so the description must hint at the return shape; it does so by naming the `id` field, which is the piece agents actually need downstream. It stops short of describing the overall response structure or how embedded `include` data is keyed, which is a minor gap for a read 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 description coverage is 100%, so both parameters are already documented in the schema. The description paraphrases the include values (omitting tax_entity and custom_field_assignments, which the schema lists) and adds no format or default details, so it only matches the schema baseline.

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

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

States a specific verb (fetch), resource (one customer), and the key selector (customer number), plus an optional expansion mode. 'One customer' implicitly distinguishes it from kickserv_list_customers, 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?

Explains the retrieval context and adds a concrete cross-tool usage rule: the returned `id` is what job/task create calls need as `customer_id`. It doesn't explicitly say when to prefer this over kickserv_list_customers or kickserv_get_job, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that related data is embedded only when requested, which is useful, but says nothing about behavior on a nonexistent job number, auth requirements, or response shape.

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

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

Two compact sentences with the core action front-loaded. The trailing 'Kickserv: GET /{account}/jobs/{job_number}.xml' is borderline noise for an agent, but it is short and does not obscure the primary statement.

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-record fetch with a fully described schema and no output schema, the description covers what is retrieved and what can be embedded. Only edge-case behavior (missing job, permissions) is absent, which is a minor gap.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description repeats the include list that the schema's enum already enumerates, adding no new syntax, cost, or interaction 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+resource+scope: fetch exactly one job by job number, with an enumerated set of optional embeds. This clearly distinguishes it from siblings like kickserv_list_jobs and kickserv_list_customer_jobs, which return collections.

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 singular 'one job by job number' implies usage versus list tools, but there is no explicit when-to-use/when-not or named alternative. An agent must infer the routing from the wording rather than being told.

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

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

readOnlyHint=true already tells the agent this is a safe non-mutating read, so the description's 'Fetch' adds little on the safety axis. It does disclose the underlying endpoint (GET /{account}/tasks/{task_id}.xml), which is mildly useful for tracing, but says nothing about error behavior for a missing id or the returned payload.

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 that are front-loaded with the action and resource, and nothing is padded. The trailing API-path sentence is arguably redundant with the title 'Get a task', which keeps it just shy 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 one-parameter read tool with no output schema and a readOnly annotation, the definition covers what the agent needs to invoke it. The main omission is any hint about the response shape or what happens when the id does not resolve.

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 parameter (task_id) and schema coverage is 100%, with the schema itself describing it as 'Task id.' and constraining it to a positive integer. The description adds no format, source, or acquisition hint beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Fetch) and resource (one task), and goes further by defining the domain term — an appointment/to-do attached to a job — which disambiguates it from unrelated uses of 'task'. It is clearly distinguishable from kickserv_create_task, though it never names a sibling explicitly.

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

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

'By id' implies the narrow lookup use case, which is adequate context for a single-record getter. However, there is no guidance on when to prefer this over listing tools (e.g. kickserv_list_jobs / kickserv_list_customer_jobs) or what to do with an id you do not have.

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 usefully adds the pagination unit (30 per page) and the underlying REST endpoint, but says nothing about ordering, filtering behavior, or what the response contains.

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: the scoping/pagination fact first, the endpoint reference second. Zero filler and nothing to trim.

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

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

A simple, read-only, fully-documented-schema listing tool with no output schema, so the description is nearly sufficient; pagination behavior is disclosed. Missing only lightweight context such as result ordering or the maximum useful page, which the schema's page maximum hints at.

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 `only`, `page`, `include`, and `customer_number` are all documented in the schema itself. The description only echoes the 30-per-page fact already present in the `page` parameter description, adding no new parameter meaning.

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 jobs') and scopes it to 'one customer', which implicitly separates it from kickserv_list_jobs (all jobs) and kickserv_get_job (single job). It stops short of naming those siblings, so an agent must infer the boundary.

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 phrase 'for one customer' plus the required customer_number signals this is the customer-scoped listing variant. There is no explicit when-to-use/when-not guidance and no named alternative such as kickserv_list_jobs, so routing depends on 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?

The readOnlyHint annotation already declares the safe read profile, so the description only needs to add context. It contributes the underlying endpoint (GET .../notes.xml), confirming a retrieval call, but discloses nothing about pagination, result ordering, empty-note behavior, or auth requirements.

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 followed by the endpoint reference; nothing is redundant. It is efficient, though the raw API path adds little for an agent that already has the structured 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 simple one-parameter read tool with annotations covering safety and no output schema, the essentials are present. However, without an output schema the description could reasonably mention the shape or pagination of returned notes and does not.

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 a single well-documented customer_number parameter, so the schema does the heavy lifting. The description adds no format or constraint detail beyond 'on one customer', which justifies 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 (notes on one customer), and the phrase 'on one customer' implicitly separates it from the sibling list_job_notes. No sibling is named explicitly, 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?

Usage is implied by the resource scoping – retrieve notes belonging to a single customer identified by customer_number. There is no explicit when-to-use guidance, no mention of the add_customer_note alternative for writing, and no prerequisites or exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=true), so the description's added value is the disclosure of pagination behavior (30 per page), the exact-match filter semantics, and the endpoint reference. It stops short of covering rate limits or what the response envelope looks like.

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 scope, then the two facts most likely to change agent behavior (exact matching, `only`), then the endpoint. 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 12-parameter, no-required-arg read tool with no output schema, the description covers pagination, filter matching semantics and response-size control. It omits any mention of the `include` embedding option, but the schema documents that fully, so the gap is minor.

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 meaning the schema does not: all filter fields are exact matches (the schema only says 'Exact' for name, phone and email, leaving billing_city, service_city, etc. ambiguous) and `only` is recommended for smaller/faster 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/search customers) and the page size, which cleanly separates it from kickserv_get_customer and kickserv_create_customer. It does not explicitly name a sibling, so it lands just short of the top band.

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?

'Every filter is an exact match on that field' and 'Use `only` to keep the response small' are genuinely useful operating constraints, but there is no routing guidance telling the agent when to prefer this over kickserv_get_customer or the more targeted list_customer_jobs/list_customer_notes. Usage is implied rather than bounded.

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 this is a safe read. The description adds a genuinely useful behavioral detail that no filter is applied (both active and inactive employees are returned) and cites the underlying endpoint. It says nothing about pagination, ordering, or result size, so it goes modestly beyond 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?

Two compact sentences with no filler; the scope of the listing is front-loaded before the follow-on guidance about the returned identifiers.

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, so the description carries some burden of describing returns; it names the two most consequential fields and the active/inactive scope. It omits other likely returned fields and any result-volume expectations, but is adequate for a zero-parameter 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 of 4 applies. The field names mentioned (id, employee_number) describe returned data rather than inputs, which is helpful context but not a parameter semantics contribution.

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 scopes it precisely: technicians and office staff, active and inactive. The employee resource is clearly distinct from the sibling list tools (customers, jobs, items, notes), so an agent can select it 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 explains downstream usage ('use their id for job/task assignment and time entries, employee_number to filter jobs') but never states when to call this tool versus an alternative, nor any preconditions or exclusions. Usage is implied by context rather than declared.

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 useful behavior beyond them: the 30-records-per-page pagination model and the active-only default filter. It does not mention auth or rate limits, but for a simple read endpoint this is a solid addition.

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

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

Front-loaded with purpose and pagination in a compact form; every sentence is short. The trailing 'Kickserv: GET /{account}/items.xml' is implementation detail of marginal value to an agent and is the only slight clutter.

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

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

For a read-only, zero-required-parameter list tool with no output schema and full schema coverage, the description covers purpose, pagination, and default filtering well. It does not hint at the shape of returned item records, a minor gap given no output schema exists.

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 fully documented. The description echoes the page size and default 'which' value but adds no syntax or filtering detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (products/services) and clarifies the domain meaning with 'the price list used for job charges'. No sibling overlaps this purpose, so differentiation is not needed.

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?

Conveys the default scope ('Active items only by default') which implies when to reach for it, but gives no explicit when-to-use/when-not guidance or alternatives. For a standalone list tool with no competing sibling this is adequate but thin.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description carries no safety burden. Beyond the annotations it only supplies the REST endpoint mapping; it says nothing about pagination, result limits, ordering, or what happens when a job has no notes.

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

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

Two short sentences with the purpose front-loaded and the endpoint detail secondary. Nothing is wasted, though the raw endpoint string earns its place only for an API-adjacent caller.

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

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

For a single-parameter read tool with readOnlyHint already declared and no output schema to explain, the description is close to sufficient. The one real gap is list behavior – pagination or result caps – which an agent might need to know.

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% for the single job_number parameter, so the schema already documents it fully. The description references "one job" but adds no format, range, or sourcing detail beyond the structured field.

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

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

The description gives a specific verb and resource ("List the notes on one job") and scopes it to a single job, which is enough to distinguish it from kickserv_list_customer_notes. It stops short of naming that sibling or any other alternative to make the distinction explicit.

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

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

Usage is implied by the scope phrase "on one job" – an agent can infer this is the read path for a job's notes. There is no statement of when to prefer it over kickserv_list_customer_notes, nor any prerequisites or exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description adds the 30-per-page pagination constant and the underlying endpoint, which is modest but real context. It says nothing about auth needs, rate limits, or what a page boundary means for iteration beyond the count.

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: capabilities and filters first, endpoint reference last. No sentence is padding, and the parenthetical glosses (work orders/estimates/invoices, job type) are load-bearing disambiguation rather than filler.

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

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

For a read-only list tool with 8 optional filters and no output schema, the description covers the essentials: scope, pagination, and the filter surface. It could be stronger by noting that responses can be trimmed with the 'only' column selector or that embedded relations come from 'include', though the schema does document both.

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 8 documented optional parameters, so the baseline is 3. The description does add one clarifying mapping — 'category (job type)' — which helps connect job_type_id to domain vocabulary, but it does not explain how the filters compose or interact.

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 usefully clarifies that 'jobs' in Kickserv spans work orders, estimates and invoices — a genuine disambiguation of the domain term. It stops short of naming siblings, so an agent cannot tell from this text alone when to prefer kickserv_list_customer_jobs over this tool.

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 enumerates the filter axes (schedule window, status, assigned employee, category, job status), which implies the situations the tool handles, but it offers no when-to-use guidance, no exclusions, and no pointer to alternatives such as kickserv_list_customer_jobs or kickserv_get_job for single-record retrieval.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description usefully clarifies that 'time entries' means technician hours and gives the REST endpoint, but says nothing about result size, pagination, or date-range behavior on a job that may have many entries.

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 core purpose front-loaded and the endpoint reference following as supporting detail.

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 with annotations covering safety and no output schema, the description is essentially complete for correct invocation. Only minor return-shape context is absent, which is acceptable given the low 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% for the single job_number parameter, so the schema carries the semantics. The description adds no format or constraint detail (e.g. how job_number is obtained) 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 (List) and resource (time entries / hours logged by technicians) scoped to one job, and even the underlying endpoint. It is distinguishable from kickserv_log_time_entry (a write) and kickserv_list_job_notes, though it does not explicitly name which sibling to prefer.

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 name and description — you call this to read time entries for a known job — but there is no explicit statement of when to use it versus kickserv_log_time_entry or kickserv_list_jobs, and no prerequisites or exclusions are given.

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, so the description carries most of the behavioral burden; it adds a 'WRITE' label and the underlying API path, which is useful context. However, it never says whether a duplicate submission creates a second entry, whether the entry can be edited/deleted afterwards, or what permissions are needed — notable gaps for an append operation flagged destructive.

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 label, then the resource action, the one cross-tool lookup note, and the endpoint. Nothing is padded and no sentence is redundant.

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 tool with no output schema, the description covers purpose and employee_id sourcing but omits what the call returns on success and where job_number and time_entry_type_id values come from. Adequate to attempt the call, but not complete enough to call it confidently.

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 genuinely adds meaning beyond the schema by telling the agent where employee_id comes from (the 'id' returned by kickserv_list_employees) rather than just 'The employee's `id`'. It does not explain time_entry_type_id, the only parameter whose source is ambiguous.

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' — clearly a time-entry write, distinguishable from sibling writes like kickserv_add_job_charge or kickserv_add_job_note. The 'WRITE:' prefix and endpoint reference reinforce the purpose, though it never names the read-side counterpart (kickserv_list_job_time_entries) it pairs with.

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 exclusion versus alternatives such as kickserv_add_job_charge, and no stated prerequisite for the job or employee existing. The only usage-adjacent help is the pointer to kickserv_list_employees for sourcing employee_id, which is a lookup hint rather than a usage rule.

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

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

Annotations only carry destructiveHint=true, and the description adds real behavioral context: the WRITE marker aligned with the destructive hint, PATCH-style partial-update semantics ('Only the fields you pass change'), and an explicit list of non-settable fields. It omits auth/permission requirements and any failure behavior for an invalid customer_number.

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 marker and the core action, then the partial-update rule, then exclusions, then the endpoint. No filler and nothing buried.

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 with no output schema, the description covers the essential risks: it is a write, it is partial, and certain fields are off-limits. Missing only permission prerequisites and error/not-found behavior, which keeps it short of a full 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 32 parameters at 100% schema description coverage, the schema already defines every field, so baseline is 3. The description adds only the meta-rule that unspecified fields are left unchanged and that balances/credit limit/custom fields cannot be passed, which is marginal but genuine added value.

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 fields on an existing customer') and immediately differentiates itself from the create/get siblings by scoping to an existing customer. The PATCH endpoint confirms the operation type without ambiguity.

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 ('existing customer', partial update by passing only changed fields) but no alternative is named explicitly, e.g. it never says to use kickserv_create_customer for new records or kickserv_get_customer to read first. The negative constraints (balances, credit limit, custom fields not settable) are useful but are limitations rather than when-to-use guidance.

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

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

Annotations only supply destructiveHint=true, so the description carries real weight: it flags the operation as a WRITE, warns that employee_ids REPLACES the current assignment, and declares which fields are non-settable. It does not cover auth requirements or response 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?

Front-loads the WRITE signal and the update verb, then the field list and endpoint. The enumerated fields make the sentence long but every clause is informative rather than 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 10-param mutation with no output schema and thin annotations, the description supplies the PATCH endpoint, the field boundaries, and replacement semantics. Only permission requirements and return behavior remain unmentioned, which is a minor gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including employee_ids replacement semantics. The description restates the field set rather than adding new meaning, 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 (update) plus resource (job) and enumerates the updatable aspects. The 'WRITE:' prefix and 'existing job' phrasing clearly separate it from kickserv_create_job and kickserv_get_job among 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?

The 'existing job' framing implies this is for pre-existing jobs rather than creation, and it explicitly excludes totals, tax and payment fields, steering agents away from unsupported edits. It stops short of naming an alternative tool for out-of-scope changes.

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