ServiceTrade MCP by usefulapi

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

Goes beyond the annotations by disclosing that each call appends a new comment, that the operation is not idempotent, and that the underlying call is POST /comment. The destructiveHint=true annotation is not contradicted, but the description could have clarified why (append-only mutation) and whether comments can be edited or deleted afterwards.

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 write classification and target resource front-loaded, followed by the one operational caveat that matters (non-idempotent). 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?

Adequate for a 4-parameter mutation: it conveys target scope, append semantics and the API endpoint. The remaining gap is the return value — with no output schema, the agent does not learn whether the created comment or its id is returned, which matters for follow-up calls.

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 content, entityId, entityType and visibility, including the asset-only public/tech restriction. The description repeats the entity types from the enum but adds no new parameter 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 (add/create) and resource (comment) and enumerates the exact record types it can attach to. The 'WRITE:' prefix and 'add a new comment' phrasing cleanly separate it from servicetrade_list_comments, which is the only near sibling.

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

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

Usage is implied by the write-oriented framing and the entity enumeration, and the non-idempotency warning gives a caution about retries. However it never explicitly says when to use this versus list_comments, nor does it state prerequisites such as needing a valid entityId or existing record.

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 the underlying REST endpoint and the shape of returned data (window, technicians, job), which is useful context, but says nothing about not-found behavior or embedded object depth.

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 operation and followed by the endpoint mapping. 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 one-parameter read tool with no output schema, the description supplies the key detail an agent needs—what the returned appointment contains. It stops short of describing the response envelope or error cases, but is largely sufficient.

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

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

Schema description coverage is 100% and the single id parameter is fully documented in the schema, so the description's 'by id' adds nothing new. Baseline 3 is appropriate.

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

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

The description states a specific verb (get) and resource (one appointment by id) and even enumerates what the record includes (window, technicians, job). The phrase 'one appointment by id' cleanly separates it from the sibling servicetrade_list_appointments.

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?

Implicit usage is clear: fetch a single appointment when you already have its id, versus listing. But no alternative is named and no when-not guidance (e.g., 'use list_appointments to find an id first') is 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?

readOnlyHint=true already declares the safety profile, so the bar is lower; the description adds the upstream endpoint (GET /asset/{id}) and hints at returned attributes. It says nothing about what happens when the id does not exist or what happens with unknown/missing ids.

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 behavior front-loaded and the API mapping trailing. Every element earns its place.

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

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

For a one-parameter read tool with readOnlyHint, full schema coverage and no output schema, the description is essentially sufficient — it identifies the record, the lookup key, and the main returned fields. Only error/not-found behavior is left unstated.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented in the schema, so the baseline of 3 applies. The description's 'by id' adds no format, range, or sourcing guidance beyond the schema's integer/exclusiveMinimum constraints.

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

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

States a specific verb and resource ('Get one asset by id') and names the salient returned fields (type, location, status). The singular 'one asset' implicitly distinguishes it from servicetrade_list_assets, but that sibling is never named explicitly.

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

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

Usage is only implied by 'by id' — an agent can infer this is the single-record lookup versus the list tool, but there is no explicit when-to-use, no prerequisite statement, and no named alternative to route against.

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 and the bar is lower. The description adds the underlying REST endpoint (GET /company/{id}), which is mildly useful for debugging, but says nothing about not-found behavior or what a company record includes.

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, purpose front-loaded, zero filler or repetition. Every sentence 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 simple single-parameter read tool with full schema coverage and no output schema, this is essentially complete; only not-found semantics and the route to a valid id are missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema fully documents it and a baseline of 3 applies. The description's "by id" adds nothing beyond what the schema already states.

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

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

States a specific verb and resource ("Get one company by id") and the singleton scope implicitly distinguishes it from the sibling servicetrade_list_companies. It never names the list sibling explicitly, so differentiation is inferred rather than 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?

The phrase "by id" implies you must already know the id, but the description gives no guidance on where to obtain one (e.g., via servicetrade_list_companies) or when to prefer this over the list tool. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by naming the salient fields returned and disclosing the underlying endpoint (GET /deficiency/{id}), but says nothing about behavior for a missing or invalid id.

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

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

Two compact sentences with the core purpose front-loaded and no filler; the endpoint reference is a cheap addition rather than padding.

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

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

For a single-parameter read tool with a covered safety annotation and no output schema, the description does enough: it names the fields an agent will get back and identifies the endpoint. Only error/not-found behavior is unaddressed.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema, so baseline 3 applies. The description's 'by id' adds nothing beyond what the schema already states.

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

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

States a specific verb and resource ('Get one deficiency by id') and enumerates the notable returned fields (severity, status, asset, reporting job). The word 'one' implicitly separates it from servicetrade_list_deficiencies, though the sibling is never named.

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

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

The phrase 'by id' implies the caller must already possess a deficiency id, which hints that list_deficiencies is the discovery step, but this is left to inference. No explicit when-to-use or when-not guidance is 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?

The readOnlyHint=true annotation already covers the safety profile, so the description's job is lighter. It usefully adds the endpoint mapping (GET /invoice/{id}) and the shape of the payload (status, items, totals), but says nothing about not-found behavior, permissions, or error responses for an id that doesn't exist.

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: the operation and its return fields come first, the endpoint mapping second. 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 compensates by naming the key returned fields (status, items, totals), which is enough for an agent to know what it gets back. Minor gaps remain around error/empty cases for an invalid id, but nothing critical is missing for a single-parameter read.

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

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

Schema description coverage is 100% and there is a single required integer id already documented as "The invoice id." The description restates "by id" without adding format, range, or sourcing guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Get one invoice by id") and enumerates the returned fields (status, items, totals), which distinguishes it from the many servicetrade_list_* siblings that return collections. It stops short of naming servicetrade_list_invoices as the alternative for finding an id, so it is clear but not maximally differentiated.

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 requires a known identifier, so the agent can infer this is a fetch-after-you-have-an-id operation rather than a search. However, no explicit guidance names servicetrade_list_invoices as the way to discover an id, and no when-not-to-use condition is stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely useful behavioral context by naming what the response contains (customer, location, owner, appointments summary, dates, price) and the underlying endpoint GET /job/{id}. It does not mention not-found/error behavior or whether the response can be expanded, which keeps 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?

Two short sentences with no filler: the payload summary is front-loaded and the API endpoint follows as secondary reference. 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 field enumeration in the description does real work by telling the agent what comes back, which is enough to decide whether this tool or the list variant answers the question. Missing only edge-case behavior such as an unknown id.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema (positive integer, the job id). The description adds only the phrase "by id" and no format or sourcing guidance 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 and resource ("Get one job by id") and enumerates the returned facets, so it is clearly distinguishable from servicetrade_list_jobs. It stops short of naming the list sibling explicitly, but "one job by id" carries the differentiation.

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

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

Usage is only implied: an agent can infer this is the detail fetch after obtaining an id from servicetrade_list_jobs, but the description never says when to prefer this over the list tool or what preconditions exist (e.g., needing a valid id). No exclusions or alternatives are stated.

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

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

readOnlyHint=true already declares this is a safe read, so the description's burden is reduced. It usefully adds the returned payload shape (address, contacts, status) and the underlying endpoint, but says nothing about behavior for a missing/invalid id, permission requirements, or whether archived locations are returned.

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

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

Two short sentences, zero filler, and the core purpose is front-loaded before the API detail. Nothing here is redundant with the schema beyond the word 'id'.

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, the description is essentially sufficient: the agent knows the input, the entity, and roughly what fields return even without an output schema. Only error/empty-case behavior is left unstated, 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?

There is a single parameter, fully documented in the schema (100% coverage) with type, minimum, and description. The description adds no meaning beyond 'by id' — no format hints, no cross-entity scope notes. Baseline 3 is right where the schema does all the work.

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: 'Get one customer location by id', and enumerates what comes back (address, contacts, status). The word 'one' plus 'by id' distinguishes it from the sibling list_locations without naming it explicitly, so the reader still has to infer the contrast.

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?

Retrieval of a single record by id is implied, but there is no explicit when-to-use or when-not-to-use guidance and no mention of servicetrade_list_locations as the alternative for enumerating locations. The agent can infer the split, but must do the work.

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 covers safety, so the description's added value is the disclosure of return contents (status, line items, totals), which matters because no output schema exists. It stops short of noting behavior for a missing or invalid id.

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

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

Two compact sentences with the core purpose and return contents front-loaded. The trailing API route reference is mildly redundant but harmless for an agent mapping to 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 single-param read tool with annotations and no output schema, the definition covers what the tool returns and its scope. Only failure behavior for a nonexistent id is left 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?

There is a single parameter with 100% schema coverage ('The quote id.'), so the schema carries the semantics. The description restates 'by id' without adding format, source, or lookup guidance, matching the baseline of 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 and resource ('Get one quote by id') and previews the payload ('status, line items and totals'), which separates it from servicetrade_list_quotes. It does not explicitly name the list sibling, so it falls just short of a 5.

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

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

Usage is only implied: 'by id' signals it is the lookup-once variant versus the list tools. There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description adds the field set returned and the underlying endpoint (GET /appointment). It says nothing about pagination limits, default ordering, or result size — which matter for an 8-param list call — so added value 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?

Two short sentences, front-loaded with the operation and its returned shape, followed by the API mapping. Nothing redundant or padded.

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

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

With 8 optional params, full schema coverage, no output schema, and safety covered by annotations, the description supplies the one thing the schema lacks: what the objects contain (time window, job, location, technicians). It omits pagination/ordering behavior, 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 filter (page, limit, jobId, techIds, windowBeginsAfter/Before, status, locationId) is already documented, and the baseline 3 applies. The description adds no format detail beyond the schema, only confirming the filterable dimensions.

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

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

Specific verb + resource ('List scheduled appointments') plus a parenthetical clarifying what an appointment is (technician visits) and which fields come back. It implicitly contrasts with the singular get_appointment sibling via 'List', but never names it 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 description implies bulk retrieval of appointments with filters, but never states when to use this versus servicetrade_get_appointment for a single record, nor when to prefer filtering by jobId vs techIds. Usage must be inferred from the tool name and schema.

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 adds the underlying endpoint (GET /asset) and the fact that results are assets scoped to customer locations, but it omits any pagination behavior despite page/limit parameters existing.

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 core purpose and followed by the API route. Nothing is padded, though the endpoint reference is marginally less useful to an agent than a usage rule would have been.

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 8 optional filter parameters and no output schema, the description should clarify the shape of returned records and pagination. It names three returned fields (type, status, name), which helps, but leaves the response envelope, total counts, and paging behavior unexplained.

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 eight parameters (including name, type, status, locationId, jobId) are already fully documented. The description only echoes the type/status/name filters and adds no syntax or semantics 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?

The description states a specific verb+resource ('List assets') and even defines the domain object with examples (extinguishers, panels, pumps), so an agent knows exactly what it retrieves. It implicitly separates itself from the singular get_asset sibling, though it never names that 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?

There is no explicit guidance on when to use this list endpoint versus servicetrade_get_asset, nor when to apply which filter. The only hint is the phrase 'at customer locations', which implies a location-scoped listing but does not state it as 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying endpoint (GET /comment), which is mildly useful for debugging, but says nothing about pagination behavior, default result cap (2000), or what a comment record contains. Adequate but thin beyond annotations.

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

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

Two short sentences, front-loaded with the core action and followed by the required inputs. The entity-type enumeration is somewhat redundant with the schema but is short enough not to be 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 six-parameter filtered list tool with no output schema, the description covers only the two identifying params and ignores pagination and the visibility/createdAfter filters. The schema fills those gaps, but the description does not explain what is returned or how results are ordered, leaving it only minimally complete.

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

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

Schema description coverage is 100%, so all six parameters including page, limit, visibility and createdAfter are already documented in the schema. The description duplicates the entityType mapping verbatim rather than adding new meaning such as valid combinations or filter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('List comments on one record') and scopes it to a single record, which cleanly separates it from list_* siblings that enumerate whole collections. It does not explicitly contrast with the sibling servicetrade_add_comment, but the read vs. write split is obvious from the verb.

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

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

It tells the caller what to pass ('the entity type number and the record id'), which implies the intended call pattern, but gives no guidance on when to use this versus add_comment, nor any prerequisites such as needing a valid record first. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /company) and notes which fields come back, but does not mention pagination behavior, default page size, ordering, or rate limits beyond what the schema 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?

Two short sentences, front-loaded with the verb and resource, with no filler. The API endpoint note is marginally useful but borders on redundant metadata.

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, all-optional list tool with no output schema, the description is adequate but thin: it doesn't describe the shape of returned company records, default sort order, or how pagination totals behave, leaving the agent to infer from the schema alone.

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, and the description adds no syntax or semantics beyond what the schema provides. Baseline 3 is appropriate when the schema does the work.

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 'List' plus resource 'companies' with entity clarifications (customers, vendors, contractors) and named filterable fields. It doesn't explicitly differentiate from the sibling servicetrade_get_company, but list-vs-get is reasonably evident from naming.

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 explicit when-to-use statement and no mention of when to prefer servicetrade_get_company (singular) for a single record. Usage is only implied by the 'List' verb and filterable fields; an agent must infer the routing.

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 the upstream endpoint (GET /contract) and the shape of returned records, which is useful context, but says nothing about pagination behavior or result volume 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?

Two short sentences with the resource and payload described first. The API endpoint line is mildly redundant for an agent but earns its place as a cross-reference to ServiceTrade documentation.

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 list tool with a fully documented schema and a readOnlyHint; no output schema exists, so the description's enumeration of returned fields (customer, location, review date, active state) usefully covers the return shape. Only the lack of guidance about when to prefer this over record-specific getters keeps it from a 5.

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

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

Schema coverage is 100%, so all six parameters (name, page, limit, active, customerId, locationId) are fully documented with defaults and bounds in the schema itself. The description's mention of customer, location, and active state mirrors those fields without adding syntax or behavioral nuance, 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 service contracts and agreements') and enumerates what each record carries (customer, location, review date, active state). The resource makes it trivially distinguishable from siblings like servicetrade_list_jobs or servicetrade_list_quotes, though it never names those siblings explicitly.

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

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

There is no when-to-use or when-not guidance, no mention of alternatives such as the get_* tools for retrieving a single record, and no prerequisites. Usage is only implied by the verb 'List' and the filterable schema.

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 externally. The description adds the endpoint and the fields surfaced (severity, status, asset), but says nothing about result volume, pagination defaults, or whether filters are combinable — gaps that matter for an 8-parameter listing tool.

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

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

Two tight sentences with the core purpose front-loaded, followed by a compact API reference. No filler, though a short note on filtering or paging would earn its place given the parameter count.

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 is the only source of return-shape information, and it names just three fields; the rest of the deficiency payload is unexplained. Combined with no guidance on pagination behavior for a 2000-per-page endpoint, it is adequate but incomplete.

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

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

Schema description coverage is 100%, so every parameter including enum-ish status and severity values is already documented. The description adds no parameter-level detail beyond what the schema provides, which is the expected baseline of 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 and resource ('List deficiencies') and defines the domain term with a parenthetical example (fire/life-safety defects) plus the API endpoint. It does not explicitly contrast with the sibling servicetrade_get_deficiency, though the list/get naming convention makes the distinction reasonably clear.

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

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

The description implies a filtered listing operation and the schema exposes status/severity/company/asset filters, but there is no statement about when to use this tool instead of servicetrade_get_deficiency or how to page through results. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the upstream endpoint, which is mildly useful context, but says nothing about pagination behavior, default page size, or default ordering — all of which matter for a 12-filter listing tool.

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 what is returned; no padding. The trailing 'ServiceTrade API: GET /invoice' is marginal but compact and gives the agent the upstream contract.

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 the fully documented schema covers all 12 optional filters. The main omission is pagination/result-size behavior, which an agent needs to know for a large collection endpoint.

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

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

Schema description coverage is 100% and every filter, enum and timestamp unit is already documented in the schema. The description's field list ('status, customer, job, totals, due date and paid state') restates what the parameters cover rather than adding syntax or interaction detail, so baseline 3 applies.

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

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

Specific verb + resource ('List invoices') with the returned fields enumerated, and the underlying endpoint (GET /invoice) confirms it is a collection read. The 'list' vs. the sibling 'servicetrade_get_invoice' distinction is implied by the verb rather than stated, 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?

Usage is only implied: the field list hints that this is for browsing/scanning invoices filtered by status, customer or job. There is no explicit guidance on when to prefer this over servicetrade_get_invoice for a single record, and no mention of paging through results.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value by mapping to the underlying endpoint (GET /job), confirming a non-mutating paginated collection read. However, it says nothing about pagination defaults, result caps, default sort order, or what happens when no filters are supplied — the operational traits an agent needs for a 17-parameter list call.

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: the first front-loads what is listed and what comes back, the second covers filtering and the endpoint mapping. No filler, no repetition of the title, and the return-field inventory is placed before the filter list where it is more useful.

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

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

For a 17-optional-parameter read tool with full schema coverage and no output schema, the description covers purpose, return fields, and filterable dimensions adequately. Gaps are minor — no note on pagination limits, sorting defaults, or whether the response is a summary vs. full job record — but an agent could invoke it correctly from this plus 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 every parameter (including enum-ish status/type values, timestamp semantics, and page/limit bounds) is already documented in structured form. The description only restates the filter categories in prose and adds no syntax, format, or interaction detail 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?

Specific verb + resource ('List jobs') with the domain subtypes spelled out (service calls, inspections, installs) and an enumeration of the fields returned (status, type, customer, location, owner, due date, estimated price). An agent can distinguish it from servicetrade_get_job by the plural/listing framing, though the description never explicitly names the single-record sibling.

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 says what can be filtered on ('Filter by status, type, location, customer, technician, due or completion dates'), which implies when the tool is appropriate — broad retrieval with narrowing criteria. But there is no explicit when-not guidance, no mention of the get_job alternative for single-record lookups, and no prerequisites stated. Usage is inferable rather than directed.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds the underlying endpoint (GET /location), which helps an API-aware agent reason about behavior. It says nothing about pagination defaults, result volume, or sort order beyond what the schema declares.

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 resource and returned fields front-loaded, no filler. The trailing 'ServiceTrade API: GET /location' is marginally useful for endpoint-aware agents rather than wasteful.

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

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

With no output schema, the description does list the returned fields, which partially compensates. However, for a six-parameter paginated list tool it omits pagination behavior and total-count semantics, leaving gaps an agent would need to discover by calling it.

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 six filters (name, page, limit, status, companyId, updatedAfter) are already documented with types and defaults. The description adds no filtering semantics or combination behavior beyond the schema, which is the expected baseline here.

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 customer service locations (sites)') and names the fields returned (address, company, status, tags), so the agent knows exactly what it gets. It does not distinguish itself from the sibling servicetrade_get_location, 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?

No explicit when-to-use guidance and no named alternative. The agent must infer that this is the bulk-retrieval counterpart to servicetrade_get_location, and nothing tells it whether pagination or filters are required for large result sets.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that records include status/customer/location/total/expiry, which is useful given no output schema, but it says nothing about pagination behavior, default sort, result volume, or rate limits that matter for a 9-parameter list tool.

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 resource and returned fields front-loaded before the endpoint reference. Nothing is wasted and nothing 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?

With 9 optional filter parameters, 100% schema coverage and a readOnly annotation, most of the burden is handled elsewhere and the description supplies the missing return-field information. However, for a list tool with no output schema it should indicate pagination/total-count semantics, which it omits.

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 9 well-documented parameters including enums for sort, sortOrder and status values, so the schema carries the semantics. The description adds no parameter-level detail (e.g. that status accepts a comma-separated list), 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 quotes') and enumerates what each record carries (status, customer, location, total, expiry), plus the underlying endpoint GET /quote. It is clearly a collection read, distinguishable by name from the sibling servicetrade_get_quote, though that sibling is never named explicitly.

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

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

No explicit when-to-use / when-not-to-use guidance is given; the agent must infer from the 'list' vs 'get' naming that this is for browsing/filtering rather than fetching one quote. The mention of the endpoint and the returned fields implies a filtered listing use case but sets no boundaries.

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. Beyond the endpoint mapping (GET /servicerequest), the description discloses nothing behavioral — no mention of default pagination, result ordering, or how filters combine. For a list tool with annotations doing the safety work, that is a thin contribution.

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

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

One tight sentence with the resource stated first and the clarifying gloss and endpoint following. No filler, though the endpoint reference is arguably redundant for an agent that cannot use it directly.

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 should at least hint at the return shape; it does so loosely via the field list in the parenthetical. However, it omits pagination behavior and result volume/ordering, and gives no guidance on combining the jobId/locationId/status filters, leaving gaps for a 5-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?

Schema description coverage is 100%, so all five parameters (page, jobId, limit, status, locationId) are already documented in the schema. The description adds no filter semantics, valid status values, or pagination notes beyond what the schema provides, 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 (List) and resource (service requests), and the parenthetical explains what a service request actually is — work items on a job with description, service line and window. It doesn't explicitly differentiate from siblings like list_jobs, but the distinct resource name is unambiguous enough for selection.

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 name and the '(the work items to perform on a job)' gloss, which hints you'd use this when you want the sub-items of a job rather than the job itself. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_jobs for job-level data).

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /user) and notes that company and status are included in results, but says nothing about pagination defaults, result caps, or the volume of data returned — relevant given the 2000-per-page limit.

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

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

Two compact clauses, front-loaded with the resource and its scope, followed by the API endpoint. Nothing is redundant, though the parenthetical list is slightly dense.

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 listing tool with full schema coverage and no output schema, the description is minimally sufficient. It would be stronger if it mentioned that results are paginated and capped at 2000 per page, since that affects how an agent should call it.

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 seven parameters (name, page, limit, isTech, search, status, companyId) are already documented. The description adds no filter semantics of its own, making baseline 3 the correct landing point.

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 users) and enumerates the user categories covered (technicians, sales staff, office staff, customer contacts), which is more than the name alone conveys. It is clearly distinct from the get_* siblings, though it never explicitly contrasts with servicetrade_get_company or servicetrade_list_companies.

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

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

Usage is only implied: an agent can infer this is the way to enumerate users, but nothing says when to use it instead of, say, pulling users via a parent company record. 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 already declare readOnlyHint=true, so safety is covered; the description adds real value by enumerating the identity fields that come back (account, company, user, timezone) and naming the underlying endpoint. It doesn't say whether ids or raw names are returned, which keeps it from a 5.

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

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

Two short sentences: the capability first, then the API reference. Every clause earns its place, with no boilerplate or repetition of the title.

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

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

For a no-parameter identity probe with readOnly annotations and no output schema, listing the returned fields goes most of the way toward telling the agent what to expect. A note on response shape (flat vs. nested, id vs. name) would fully close the 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?

The tool takes zero parameters, so the baseline is 4; nothing about the description misleads the agent into passing arguments.

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 concrete verb ('Show') and a precise resource: the account, company, user and timezone of the connected credential. This is clearly distinguishable from every sibling, all of which fetch or list domain entities rather than identity information.

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 connected credential' plus the oauth2/userinfo endpoint makes the use case (verify who you are authenticated as / resolve the current user before other calls) fairly clear without stating it. No explicit when-not-to-use or prerequisites are given, 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.