Service Fusion MCP by usefulapi

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

Annotations only say destructive/openWorld/non-idempotent; the description adds the substantive meaning behind those flags: team-wide visibility, no delete path through the API, and duplicate names silently producing two records. That is exactly the extra context an agent needs before a non-reversible write, and it is consistent with 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?

Three short sentences, front-loaded with the operation class and the duplicate trap, closing with the endpoint for developers. Nothing is repeated from the title or annotations, and no sentence is 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?

The safety story is complete, but for a 23-parameter creation tool with no output schema, the description never says what comes back (e.g., the new customer ID) or how nested contacts/locations relate to the top-level record. Adequate to call safely, thin on what to expect afterward and on the ignored-but-numerous optional fields.

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

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

Schema description coverage is only 26% across 23 parameters, so the description carries most of the explanatory burden — but it only touches contacts and locations, leaving high-impact fields like parent_customer, custom_fields, credit_rating, discount_type, and labor_charge_type to bare names and enums. It adds no format, ordering, or default guidance 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?

Starts with an explicit operation class ("WRITE: create a customer") plus the resource and the optional sub-objects it accepts (contacts, service locations), so the agent knows exactly what it creates. It also distinguishes itself from the read-side sibling by naming servicefusion_list_customers as the lookup tool rather than a creator.

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 precondition ("search with servicefusion_list_customers first") and names the exact sibling to use, along with the consequence of skipping it (duplicate customers). It also flags that this is a write path, which separates it from all the get_/list_ siblings in the toolset.

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 readOnly=false, destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description still adds concrete consequences the annotations don't spell out: the estimate cannot be deleted via this API, duplicate calls create duplicate records, and it maps to POST /estimates. It omits auth requirements and 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 dense sentences plus an endpoint token; the "WRITE:" prefix and the resource statement are front-loaded, and the irreversibility caveat follows immediately. Nothing is padded.

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

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

For a 35-parameter mutation with no output schema, the description covers the mutation semantics well but leaves out what is returned (e.g., the new estimate ID) and how to retrieve the created record. There is also no mention of permissions or field-level constraints an agent would need before assembling a large nested payload.

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 46% across 35 parameters, so the description must compensate and does so only partially by enumerating payload sections (address, category, source, technicians, tasks, notes, products, services, other charges, tags). Many scalar fields — project, contract, phase, is_gated, gate_instructions, po_number — get no semantic clarification beyond their names, and the customer_name auto-create behavior lives only in 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?

Opens with a specific verb and resource ("WRITE: create an estimate (quote) for a customer") and enumerates the optional payload sections, so the scope is unambiguous. It does not explicitly contrast itself with create_job or create_customer, relying on the resource name to differentiate.

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 name — an agent knows this is the way to create an estimate — and the non-idempotency warning ("creating twice makes two estimates") tells it to check for duplicates first. However, there is no explicit guidance on when to prefer create_job versus create_estimate, or on prerequisites such as customer existence.

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 idempotentHint=false, and the description reinforces with concrete consequences: the job "appears on the team's schedule" and "cannot be deleted through this API; creating twice makes two jobs." It does not cover permissions/auth needs or the response payload, keeping it below a 5.

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

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

Three sentences, front-loaded with the read/write marker and the core action, ending with the endpoint. The field enumeration is long but aids scanning of a 40-parameter schema; little is wasted, though some of the list duplicates schema keys.

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 destructive, non-idempotent 40-parameter creation tool with no output schema, the description covers the key risks (no delete, duplicate creation) and lookup prerequisites, but never says what is returned (e.g., the new job ID) or how partial payload failures behave. That leaves a meaningful gap for an agent planning a follow-up get_job call.

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 35% across 40 parameters, so the description must compensate and does so only partly: it enumerates the optional groups (address, category, source, techs, tasks, notes, products, services, other charges) and points to lookup tools for name-based fields. Roughly two-thirds of parameters — dates, duration, payment fields, custom_fields, gate/follow-up flags — get no mention in the description.

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

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

Opens with a specific verb and resource ("create a job (work order) for a customer") plus a scoping note on optional groups, which cleanly separates it from siblings like servicefusion_create_customer and servicefusion_create_estimate. The parenthetical clarifying "work order" also resolves terminology 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?

Gives an explicit prerequisite ("Look up category, source and status names with the list tools first"), naming the sibling list tools conceptually. It states no exclusion criteria against create_estimate, but the domain context (job vs. estimate) is reasonably implied by the resource 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 declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description's main behavioral detail is the 8-day / 7-day window cap, but that is repeated verbatim in the end_date schema description, so it adds little beyond structured data. No mention of pagination or result volume behavior in the prose.

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 front-loads what the tool returns, then lists filters and the endpoint. Zero padding. The trailing 'GET /availability' is marginally redundant 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?

With 15 parameters and no output schema, the description should say something about the shape of a returned slot (fields, ordering, pagination signal) so the agent knows how to consume results. It confirms the tool returns slots but not their structure, leaving a meaningful gap for an output-schema-less tool.

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

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

Schema coverage is 100%, so the schema already documents all 15 parameters in detail. The description only lists the filter categories (technician, crew, department, experience level, slot length) at a high level, adding no syntax or semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Open time slots for technicians and/or crews') and names the scope coverage. It is clearly distinguishable from siblings like get_tech or list_techs, which retrieve entities rather than availability. Not quite a 5 because it doesn't call out a specific contrasting sibling by name.

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

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

Usage is implied (find open slots for scheduling) and the enumeration of filters signals it's a search tool, but there's no explicit 'use when' guidance or routing to/from alternatives. The agent must infer this is the availability-lookup tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond repeating 'GET' and the path — no note on what happens for missing/invalid ids, how expansion of 'repeat' changes the payload, 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 very short sentences, front-loaded with the operation and scope. The endpoint echo adds little but costs almost nothing, so there is minimal waste.

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

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

For a simple read tool with full schema coverage and annotations, the essentials are present. However, with no output schema the description gives no hint of the returned calendar-task shape, and it does not mention the expand/fields behaviors that materially change the response.

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 calendar_task_id, expand and fields including formats and defaults. The description adds no parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb and resource: retrieve a single calendar task by id, and the endpoint path confirms it. It implicitly distinguishes itself from the list_calendar_tasks sibling by 'by id', though it never names that sibling explicitly.

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

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

The 'by id' phrasing implies this is the single-fetch variant when the id is already known, but there is no explicit when-to-use statement, no mention of the list sibling, and no note on error behavior for unknown ids.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that technicians can optionally be attached and cites the REST endpoint; it says nothing about error behavior for missing crews, response shape, or whether expansion changes payload size.

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

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

Two compact sentences, front-loaded with the operation and scope. The trailing 'GET /crews/{id}' is mildly redundant with the name and schema but is a cheap, unambiguous anchor for an API-wrapper tool; nothing else is wasted.

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

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

For a single-record read with three fully documented parameters, annotations covering safety, and no output schema, the description supplies enough to call it correctly. The remaining gap is only what the response contains and how errors surface, 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 description coverage is 100%, so the schema itself documents crew_id, expand (enum 'techs'), and fields (comma-separated projection). The description echoes the expand behavior ('optionally with its technicians') but adds no syntax or constraint detail 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 ('one crew by id') plus the optional expansion ('with its technicians'), and the underlying endpoint GET /crews/{id} confirms the singular-lookup semantics. It implicitly separates itself from servicefusion_list_crews by saying 'one crew by id', but never names the 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?

Usage is only implied: 'by id' signals a single-record lookup versus the list tool, but there is no explicit when-to-use guidance, no statement about when to add the techs expansion versus calling a tech endpoint, and no prerequisites or error conditions (e.g., nonexistent id).

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context that the expansion of contacts/phones/emails/locations/custom_fields is optional and multiplicative on payload size, plus the underlying endpoint. It says nothing about error behavior for a missing id or permissions.

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, both front-loaded: the scope of the read comes first, the optional expansions second, and the endpoint last. The trailing 'GET /customers/{id}' is near-redundant but costs almost nothing and clarifies the REST mapping.

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?

The tool is a simple single-resource read with a fully described schema and read-only annotations, so the essentials are covered. However, there is no output schema and the description does not indicate the shape of the returned customer object or how sparse fieldsets via 'fields' affect it, leaving a small but real gap.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema with an enum list for expand and a pattern example for fields. The description only restates the expandable resources, adding no syntax or constraint meaning beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb ('get') and singular resource ('one customer by id'), which clearly separates it from the sibling servicefusion_list_customers. It does not explicitly name any sibling, but the singular-vs-list distinction is legible from 'one customer by id'.

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

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

There is no when-to-use guidance and no named alternative; the agent must infer on its own that list_customers is the choice when the id is unknown. The only implicit signal is 'by id', which leaves prerequisite discovery 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds nothing beyond what the endpoint string implies — no mention of 404/not-found behavior, whether fields/expand affect the shape, 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 short sentences with nothing extraneous, but the second sentence merely restates the two already-required path parameters and carries no added meaning. Efficient in length, thin in value.

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

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

For a simple single-record read with full schema coverage and read-only annotations, this is minimally adequate. It omits what the response looks like and whether a missing equipment_id returns an error, which the lack of an output schema would otherwise require.

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 four parameters (customer_id, equipment_id, expand, fields) are already documented in the schema. The description adds no interpretation beyond the path parameters, so baseline 3 applies.

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

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

The description says it returns 'one piece of equipment of a customer' and gives the GET path, which implies a single-record retrieval. But it is a noun phrase with no verb, and the singular-vs-list distinction against servicefusion_list_customer_equipment is only implied by 'one', not stated.

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

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

No guidance on when to use this versus listing equipment first, or versus the parent customer lookup. The only hint is the schema note on equipment_id ('from servicefusion_list_customer_equipment'), which is in the schema, not the description.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that optional expansions pull in related data (line items, techs, notes, tags), but says nothing about error behavior for a missing id, response size costs of heavy expansions, 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 compact sentences, front-loaded with the core action and leaving the route as a trailing identifier. The phrase 'and more' is slight filler since the schema enumerates all options, but overall there is little waste.

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

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

With no output schema, the description does not say what fields a returned estimate carries or what the expanded payloads look like, which leaves an agent guessing about return shape. For a simple annotated read tool with full parameter documentation this is adequate but not rich.

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 expand enum is fully enumerated in the schema, so the baseline of 3 applies. The description's mention of 'line items, technicians, notes, tags and more' loosely gestures at the expand options but adds no syntax or cost information 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: retrieves a single estimate by id, with the HTTP route GET /estimates/{id} reinforcing the singular fetch semantics. This implicitly distinguishes it from servicefusion_list_estimates, though it never names that sibling explicitly.

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

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

Usage is only implied: an agent infers this is for fetching details when it already has an estimate id. There is no statement of when to prefer this over list_estimates, or any prerequisites such as the id needing to exist.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds only the endpoint path, which reinforces read-only behavior but does not provide additional behavioral context such as authentication requirements, rate limits, 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?

The description is extremely short and front-loaded, containing no filler. Both fragments directly identify the operation and 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?

For a simple read-by-id tool with complete schema descriptions and read-only annotations, the description is minimally adequate. It does not explain return shape or error cases, but the absence of an output schema means those details are not strictly required here.

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 input schema already documents both invoice_id and fields thoroughly. The description adds no parameter meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: retrieve one invoice by id. It implicitly distinguishes itself from servicefusion_list_invoices by emphasizing a single invoice and the id-based endpoint, though it does not explicitly name the sibling alternative.

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 the tool is used when the invoice id is already known, but there is no explicit guidance on when to prefer this over servicefusion_list_invoices. Alternatives and exclusions are left 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 and destructiveHint=false, so safety is covered. The description adds the underlying endpoint (GET /jobs/{id}) and that expansions are opt-in, but says nothing about permissions, missing-record behavior, 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?

One sentence plus the endpoint path, with the resource and id-scoping front-loaded and zero 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?

With no output schema, an agent knows what to send and roughly what comes back (job plus optional expansions). It could say more about the default payload beyond the expanded sections, but it is sufficient for a straightforward getter.

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 params including the full expand enum are already documented in the schema. The description's mention of expandable sections adds only a hint; it does not explain fields or pagination beyond the schema. 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 ('One job by id') plus the optional expansions, which makes it clearly distinct from the sibling servicefusion_list_jobs. It never names an alternative explicitly, so it stops 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 singular 'by id' framing implies the fetch-one-record use case, but there is no explicit when-to-use, when-not, or pointer to list_jobs for bulk retrieval. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by naming the exact fields returned (id, name, email) and the raw endpoint, which lets the agent know this is a lightweight identity read with no side effects.

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 the endpoint path, with the resource identity front-loaded and the usage hint immediately after. Nothing is padded and 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?

With no output schema, the description compensates by listing the returned fields, and with zero params and full annotation coverage there is little else an agent needs. It could optionally note that an auth failure surfaces as an error, but the definition is otherwise sufficient to call correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no argument semantics to document. The description correctly implies no inputs are required by framing the call as a pure credential/connection check.

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

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

States a specific resource and scope: 'the Service Fusion user the API credentials belong to,' with the returned fields (id, name, email) enumerated. This clearly separates it from the customer/job/estimate getters among its siblings, which fetch domain records rather than the authenticated identity.

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 an explicit use case — 'Use it to check the connection' — which is exactly the when-to-use signal an agent needs for a /me endpoint. No exclusion is stated, but there is no competing tool for fetching the authenticated user, so nothing is left ambiguous.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /techs/{id}), reinforcing that this is a direct non-mutating lookup, but says nothing about behavior on a missing id, permissions, or return shape.

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

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

Two short, front-loaded sentences with no filler; the resource scope comes first and the endpoint mapping second. It is efficient, though the endpoint path is of marginal value to an agent that cannot call raw HTTP.

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 two-parameter read tool with full annotations and full schema coverage, the description is adequate but thin: it omits what a technician record contains and how a not-found id behaves, and with no output schema the return value is left entirely unspecified.

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

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

Schema description coverage is 100%, with tech_id and the fields projection both documented in the schema itself. The description only restates that the lookup is by id, adding no format or semantics 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?

The description states a specific verb and resource plus scope: "One technician by id," which contrasts with the sibling list_techs by implying a single-record fetch. It falls short of a 5 because it never names the sibling or explicitly says it is not the list operation.

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 precondition that the agent already holds a tech id, but there is no explicit when-to-use guidance, no mention of list_techs as the alternative for browsing, and no note about related lookups like get_crew or get_me.

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 destructiveHint=false, so safety is covered. The description adds the useful overlap semantics ('A task is returned when it overlaps the range') and the GET endpoint. It does not mention pagination behavior beyond the schema's next_page hint 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 compact sentences front-load the resource and filtering modes, then the overlap rule and endpoint. 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 a read-only list tool with fully documented schema and clear annotations, the description covers scope and overlap behavior adequately. Minor gap: no explicit return-shape or ordering note, but that's mostly covered by fields/sort parameters.

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 the start_date/end_date single-day-vs-range rule. The description restates that rule but adds no additional parameter meaning 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?

Description states a clear verb (List) and resource (calendar tasks), and parenthetically defines what a calendar task is (appointments and to-dos on the schedule). It does not explicitly distinguish from get_calendar_task, though the plural/list form makes the split inferable.

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 explains the filtering modes: one date alone for a single day, both dates for a range, and/or user_ids. It gives clear conditions for parameter combinations but doesn't explicitly say when to prefer this over get_calendar_task or get_availability.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the endpoint path and the fact that member data is optional, but says nothing about pagination behavior, result size, or what a crew record contains beyond its members.

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

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

A single compact sentence plus the endpoint — definition and key optional behavior are front-loaded with zero wasted text.

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

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

For a read-only list tool with a fully documented schema and no output schema, the description is sufficient to call it correctly. The main missing piece is the relationship to servicefusion_get_crew and any note on result shape, but nothing essential is absent.

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 paging, sort, fields and per_page are fully documented in the schema and the baseline is 3. The description only loosely ties 'members' to the expand=techs parameter, adding marginal meaning 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 (List crews) and adds a useful definition — 'named groups of technicians' — plus the underlying endpoint GET /crews. It implicitly contrasts with the singular get_crew sibling by describing a collection listing, but never names that sibling, so it stops 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?

'optionally with their members' hints at when to use the expand option, but there is no explicit when-to-use guidance and no routing to servicefusion_get_crew for fetching a single crew. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the REST endpoint and the returned field set, but says nothing about pagination limits, result caps, or auth requirements beyond the structured fields.

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, no waste: the resource and returned fields come first, and the endpoint is appended as a compact identifier. 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?

With no output schema, the description usefully names the fields returned, and pagination/sorting are covered by the schema. The only gap is the lack of explicit differentiation from the single-record get_customer_equipment 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 description coverage is 100%, so paging, sorting, field selection and expand are fully documented in the schema itself. The description contributes no additional parameter meaning, which is the correct baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the equipment on file for a customer') and even enumerates the fields returned (make, model, serial, warranty/install dates), so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling get_customer_equipment, leaving the list-vs-single distinction to be inferred from the names.

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 'for a customer' framing and the required customer_id, but there is no explicit when-to-use guidance, no mention of when to prefer get_customer_equipment, and no note about how to page through large equipment sets beyond what the schema says.

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 destructiveHint=false, so safety is covered. The description adds the default sort order and the hint that related entities must be opted into via expand, which is genuinely useful, but says nothing about pagination limits (per_page max 50) or what happens when expand is omitted beyond the schema.

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

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

Three tight sentences, front-loaded with the resource and default order, followed by filtering and expand guidance. The trailing 'GET /customers.' earns little but is harmless endpoint context.

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 16-parameter list tool with no output schema, the description covers filtering and expansion but omits pagination behavior and anything about the response envelope (aside from the schema's next_page hint). Adequate but with clear gaps an agent would benefit from.

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 16 parameters including match semantics (partial vs exact) and sort syntax are already documented in the schema. The description's parameter mentions largely restate that surface, warranting 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 ('customers') plus the default ordering ('newest id order unless sorted') and the filterable dimensions. This clearly separates it from the singular servicefusion_get_customer, though the description never names that sibling explicitly.

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

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

Usage is implied through the filter list and the 'add expand=... to include them' instruction, which tells the agent when to opt into extra data. However, there is no explicit when-to-use/when-not or routing to alternatives (e.g. get_customer for a single record), so the agent must infer selection.

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

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

Annotations already cover readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is known. The description adds the endpoint 'GET /estimates' and a list of filterable fields, but does not disclose pagination behavior, rate limits, authentication needs, or match-type behavior beyond what the schema already states.

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 immediately followed by supported filters and the HTTP endpoint. There is no repetition or wasted text.

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

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

For a 25-parameter list tool with 100% schema coverage and no output schema, the description gives the core purpose and filter scope. Pagination, sorting, field selection, and expansion are omitted from the description but fully documented in the schema, leaving only minor contextual gaps.

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

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

Schema description coverage is 100%, so every parameter is already documented with type, format, and match semantics. The description only restates a subset of filter fields and adds no format or matching detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: 'List estimates (quotes).' It is clearly distinguishable from create_estimate and get_estimate because it is the list operation, though it does not explicitly name those siblings or contrast the use case.

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 'Filter by status, number, PO number, customer...' implies the tool is used for filtered estimate searches, but there is no explicit guidance on when to use this instead of get_estimate or how to handle pagination. Usage is implied rather than prescribed.

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 destructiveHint=false, so safety is covered; the description adds genuinely useful non-obvious behavior — the absence of filter parameters — which prevents an agent from fruitlessly searching for a filter argument. It also names the underlying endpoint, aiding debugging, though it says little about paging limits or result-size behavior (which the schema carries).

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: what you get, the key constraint with the workaround, and the endpoint. Front-loaded and free of filler; every sentence carries information an 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?

With no output schema, the description compensates by enumerating the returned fields, and the annotations cover the safety profile. Combined with fully documented parameters, an agent has what it needs to call this correctly; only the pagination envelope (next_page) is left implicit to 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 page, sort, fields and per_page are all fully documented in the schema, including the leading-minus sort syntax and the next_page handoff. The description's sort example duplicates rather than extends schema content, so baseline 3 applies.

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

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

States a specific verb and resource ('List invoices') and enumerates what each record contains (number, total, paid flag, dates, customer), which distinguishes it from the singular servicefusion_get_invoice sibling by implication of plural listing. It does not explicitly name that sibling, so differentiation is only partial.

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 usage constraint: the API has no invoice filters, so the agent must sort and page instead, with an example (sort=-date). It stops short of saying when to prefer servicefusion_get_invoice or other retrieval paths, but the key operational guidance is present.

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 destructiveHint=false, and the raw GET endpoint reinforces that this is a harmless read. The description adds nothing about the response shape, result size, or whether pagination typically requires multiple calls — modest value beyond structured fields.

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 fragments with the purpose front-loaded and zero filler. Slightly clipped — it reads as a note rather than a description — but nothing is wasted.

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

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

With no output schema, the description should say what a category record contains (e.g. an id plus name) since an agent likely needs the id to set on a job. It only says 'names', leaving a real gap for a reference-data lookup.

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 page, per_page, sort, and fields all documented inline, so the description needs to add nothing and adds nothing. 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?

Identifies a specific resource (job categories) and its intended use, plus the backing endpoint GET /job-categories, which makes the list semantics unambiguous. It never uses an explicit verb like 'list' and does not distinguish itself from siblings, but no sibling covers categories so confusion risk is low.

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

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

'to use when creating or filtering jobs' explains when the returned values are useful, which implies the calling context. It does not say when to call this versus other reference lookups, nor give pagination/iteration advice beyond what the schema already states.

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, destructiveHint=false, and openWorldHint=true. The description adds useful behavior around expand and notes GET /jobs, but does not mention pagination behavior, rate limits, auth needs, or return 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?

Front-loaded and compact, with filters and expand grouped efficiently. The trailing 'GET /jobs' is mildly redundant given readOnlyHint but not harmful.

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?

Complete enough for a paginated list tool: it explains filters, expand, and endpoint, while the schema covers pagination and field details. Lacking an output schema, it could say more about returned job records, but that is a minor gap.

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

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

Schema description coverage is 100%, so all 28 parameters are already documented. The description groups filters and mentions expand examples, but adds little semantic detail beyond what the schema provides.

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 and resource: 'List jobs (work orders).' It is easy to distinguish from get_job or list_customers, though it does not explicitly name sibling alternatives.

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

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

The filter list implies how to use the tool for searching jobs, and expand is described for detail. However, there is no explicit guidance on when to use this versus get_job or when to consult list_job_statuses/list_sources.

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 read-only, non-destructive, open-world behavior. The description adds that this is a reference list of status names/fields rather than job records, plus the endpoint, which is sufficient context for a simple lookup; pagination details are left to the schema.

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

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

Two compact sentences front-load the returned resource and its use, with no filler. The endpoint mention is a small but relevant 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 simple read-only lookup with fully described parameters and no output schema, the description supplies the returned fields and intended use. It need not explain the response envelope or pagination because the schema covers pagination.

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 page, per_page, sort, and fields are fully documented in the schema. The description adds no parameter-specific semantics beyond 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?

The description names the resource and the exact fields returned (code, name, custom flag, category), and ties them to creating or filtering jobs. It is clearly distinguishable from list_jobs and list_job_categories, though it relies on the title for the verb 'List'.

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

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

It states the practical use case: retrieving job status names to use when creating or filtering jobs. It does not name explicit alternatives or when-not-to-use cases, so it provides clear context without 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. Beyond restating the resource, the description only adds the raw endpoint path 'GET /payment-types', with no note on result size, caching, or whether the list is stable/complete.

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 fragments with zero filler; the resource scoping is front-loaded. It could be tightened into a single clear sentence, but nothing is wasted.

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

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

There is no output schema, so the description is the only place an agent could learn what a payment type record contains (id, name, etc.) or that results are paginated — and it says nothing about the return shape. For a tiny description on a paginated list tool, this leaves a real gap.

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

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

Schema coverage is 100%: page, sort, fields and per_page each carry their own description, pattern and bounds. The tool description adds no additional parameter 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?

The description names the specific resource ('payment types configured in the account') and the endpoint, which distinguishes it from sibling list tools such as list_job_statuses and list_sources. It is a noun phrase rather than a verb phrase, but combined with the name 'list_payment_types' the operation is unambiguous.

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

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

There is no statement of when to use this tool, no prerequisites, and no mention of alternatives or when not to call it. An agent must infer that this is a reference-data lookup used before creating or filtering payments.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns short and long names and the underlying endpoint, but it does not discuss pagination behavior, authentication needs, or any other behavioral traits beyond what annotations and schema provide.

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 wasted words. The resource and its purpose are front-loaded before the endpoint reference. Every part of the description 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 simple reference-list tool with full schema documentation, annotations covering safety, and no output schema, the description is largely complete. It states what the tool returns (short and long names) and its intended use. It could mention pagination or that it is meant for populating dropdowns, but those are minor gaps given the structured fields already present.

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 fully documents page, sort, fields, and per_page. The description adds no parameter-specific meaning beyond the schema. A baseline of 3 is appropriate when the schema does the heavy lifting and the description does not compensate further.

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

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

The description identifies the exact resource (lead/referral sources with short and long names) and its role in creating or filtering jobs and estimates. The endpoint 'GET /sources' reinforces the operation. It distinguishes itself from siblings like list_job_statuses or list_payment_types by naming the distinct resource, though it does not explicitly contrast with them.

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

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

It clearly states the context for use: 'to use when creating or filtering jobs and estimates.' This tells an agent when to call it, but it does not explicitly name alternatives or when not to use it. The guidance is strong for a reference-list tool but stops short of full routing instructions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds that this is a plain GET endpoint returning account-configured names, but says nothing about ordering, empty results, or whether departments are user-managed vs. system-defined.

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

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

A single sentence plus the endpoint path, front-loaded with the resource and the practical use case. Nothing is wasted and nothing essential 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 zero-parameter read tool with no output schema, the description adequately conveys what comes back ('department names') and where it comes from. It could add slight detail on the shape of the returned list, but the essentials for correct invocation are present.

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 per the rubric the baseline is 4. The description correctly implies no inputs are needed and does not invent any, leaving nothing ambiguous for the agent.

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 clearly identifies the resource ('technician department names configured in the account') and implicitly states the operation (list/retrieve), distinguishing it from siblings such as servicefusion_list_techs and servicefusion_get_tech. It stops short of an explicit verb like 'list', but the resource is unambiguous.

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

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

The parenthetical '(useful for availability filters)' names a concrete use case that links this tool to servicefusion_get_availability, giving the agent clear context for when to reach for it. It does not state exclusions or name the alternative tool explicitly, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful scope clarity by noting sales reps are included in the same result set — a non-obvious trait — but says nothing about pagination behavior, default result counts, or response shape beyond the field list.

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

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

One dense sentence plus the endpoint — front-loaded with the resource and zero filler. The parenthetical field list is compact but slightly crowds the sentence; it still earns its place by conveying return shape.

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

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

With no output schema, the description usefully compensates by listing the returned fields and clarifying that sales reps are included alongside technicians. It remains thin on pagination and filter behavior, though the 100%-covered schema fills those 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%, with every parameter (page, sort, fields, per_page, name filters) fully documented in the schema. The description's field list loosely hints at what the 'fields' param can select but adds no filtering, sorting, or pagination semantics beyond the schema — baseline 3 applies.

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

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

States a specific verb+resource ('List technicians and sales reps') and enumerates the returned attributes plus the underlying endpoint, so the agent knows exactly what comes back. It does not explicitly name the sibling servicefusion_get_tech as the single-record counterpart, leaving that distinction to the list/get naming convention.

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 verb 'List' — the agent can infer this is the browse/enumerate tool, but the description never says when to use it versus get_tech for a specific technician or list_tech_departments for department data.

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