ServiceMonster MCP by usefulapi

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

Adds substantial context beyond destructiveHint=true: the write is immediate with no preview or separate confirmation step, the permission model (Read Only cannot write), and an explicit caution to confirm the target record and text with the user beforehand. This is exactly the safety-relevant disclosure an agent needs before invoking a destructive write.

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

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

Four short, front-loaded sentences covering action, immediacy, permissions, targeting constraints and the confirmation step; nothing is redundant with the annotations or the schema, 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?

For a destructive 5-parameter write with no output schema, the description covers permissions, targeting rules, irreversibility/confirmation posture and scope exclusions. It does not indicate what the call returns (e.g., created note ID) nor the 20000-character note limit, a minor remaining gap.

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

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

Schema coverage is 60% and the schema's UUID fields only say 'obtained from a preceding read', so the description's mutual-exclusivity rule for orderID vs siteID is genuinely additive information not present in the schema. The subject/note fields and their length limits are left entirely to the schema, so it doesn't cover every parameter.

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

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

States a specific verb and resource ('Create a note immediately (POST /v1/notes)') and clarifies the three attachment targets (account, order, site), which cleanly separates it from the read-oriented siblings like servicemonster_get_note and servicemonster_list_notes.

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

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

Gives concrete preconditions: must supply accountID, orderID or siteID, orderID and siteID are mutually exclusive, API User permission required (Read Only cannot write), and the agent should ask the user to review the exact record and text first. It also excludes adjacent use cases ('No scheduling or messaging is performed'). It stops short of naming a specific alternative tool, hence not a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's contribution is minimal. It adds the raw endpoint path, which hints at a single-record lookup, but says nothing about the returned shape, error behavior for a missing/invalid GUID, or authorization scope.

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 terse sentences with no waste and the core action stated first. The terseness borders on under-specification, but nothing is padded or 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 no output schema, the description carries responsibility for at least sketching what a fetched account record contains, and it does not. For a one-parameter read tool this is a significant omission, leaving the agent to guess at the 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 100% and the single `id` parameter is fully documented in the schema, including UUID format and the note that it comes from a preceding read. The description adds no parameter meaning 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 pairs a generic verb ("Read") with an ambiguous object ("the selected record"), which only becomes concrete through the REST path GET /v1/accounts/{id}. The resource is inferable from the endpoint and the title, but the description itself never says "account" and never distinguishes this from siblings like servicemonster_get_account_profile.

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

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

No when-to-use guidance is given, and nothing distinguishes this single-account fetch from servicemonster_get_account_profile or the list_accounts variant. The only implicit signal is the {id} path parameter, which the agent must decode itself.

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 structurally. The description adds nothing beyond that — no note on authentication, pagination, stale/refresh behavior of the statistics, or error behavior when an account has no orders. The endpoint path is the only extra detail and it is not behaviorally meaningful.

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

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

Two short sentences, front-loaded with the verb and the returned content. The second sentence is a bare endpoint reference that borders on filler but is at least terse and non-redundant.

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

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

For a read-only single-parameter tool this is close to adequate, and naming the returned content (statistics, balance) partially compensates for the absent output schema. It still leaves the agent guessing about the shape of the profile payload and how it differs from get_account.

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?

Only one parameter and schema description coverage is 100%, with the schema already explaining the GUID format and its provenance. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('account's service/order history statistics and available balance information'), which is more informative than the title alone. It does not explicitly distinguish itself from the sibling servicemonster_get_account, which an agent could easily confuse it with.

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

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

The description says what data is returned but gives no when-to-use guidance, no prerequisites (e.g., that the id must come from a prior read — that is only in the schema), and no mention of alternatives such as get_account or list_account_orders. The 'GET /v1/accounts/{id}/profile' line is an endpoint reference, not usage guidance.

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

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

readOnlyHint=true already declares the safety profile, so the description adds nothing on that front. Beyond restating the HTTP verb and path, it discloses nothing about error behavior for unknown ids, response shape, or expansion options.

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 and waste-free. It is on the thin side rather than verbose, so conciseness itself is not a problem.

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 place an agent could learn what a job record contains, and it says nothing about return fields or structure. For a lookup tool that will feed further calls, that 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% and the id parameter is fully documented in the schema (UUID format, pattern, and provenance). The description adds no parameter detail, which is acceptable given the schema does the work — 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?

The endpoint notation 'GET /v1/jobs/{id}' plus 'Read the selected record' makes clear this retrieves a single job by identifier, distinguishing it from the many list_* siblings. The phrase 'the selected record' is slightly vague on its own, but the path resolves it.

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 servicemonster_list_jobs or servicemonster_list_order_jobs, and no note that the id typically comes from a preceding list call. The only clue is the schema's own note about obtaining the GUID from a prior read.

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 only the raw HTTP route, with no information on what happens when the id does not exist (404/empty), whether related sub-resources are included, or any response shape hints.

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 zero redundancy. It is efficient, though the first sentence is vague enough that its brevity costs clarity rather than earning it.

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 a readOnly annotation, the definition is minimally sufficient to call the tool. It still leaves the agent guessing about not-found behavior and how it relates to the list_notes siblings.

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%: the single id parameter is fully documented as a UUID GUID obtained from a preceding read, including a pattern. The description adds nothing beyond that, so the baseline 3 for high schema coverage 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 verb 'Read' plus the endpoint path 'GET /v1/notes/{id}' implies fetching a single note, but the description says 'the selected record' rather than naming a note explicitly. It never distinguishes itself from siblings like servicemonster_list_notes or servicemonster_get_account, so an agent must infer the resource from the tool 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?

There is no guidance on when to use this versus servicemonster_list_notes or servicemonster_list_account_notes, and no mention that an id must first be obtained from a list call. Usage is only implied by the endpoint path.

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 only the raw endpoint path, with no information about error behavior for bad/unknown GUIDs, whether the record is authoritative, or what fields come back.

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 terse sentences with no waste, but 'Read the selected record' is a low-information filler phrase and the endpoint path carries most of the meaning. It is concise without being informative.

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 with readOnlyHint and no output schema, the essentials are close to covered, but the description never states what an order record contains or what happens on a missing id. Adequate, with visible gaps.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented as a ServiceMonster record GUID from a preceding read. The description adds no syntax or sourcing detail beyond that, 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 verb 'Read' plus the endpoint path 'GET /v1/orders/{id}' implies it fetches a single order by id, and the singular form distinguishes it from list_orders only by inference. The phrase 'the selected record' is vague and never names the resource outright, so the agent relies on the tool name to confirm it operates on orders.

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 versus the many siblings, notably servicemonster_list_orders or servicemonster_list_account_orders. The single-id shape hints at fetching one known record, but that must be inferred rather than read.

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 elsewhere. The description adds essentially nothing beyond restating that it is a read plus the HTTP path — no note on what is returned, what happens on an unknown/expired id, or any auth/rate-limit context.

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, nothing to trim. The first sentence is close to tautological filler, but the second immediately supplies the concrete 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 trivial one-parameter read with readOnlyHint and a fully documented schema, the definition is minimally sufficient. It still leaves the agent without any hint of the response shape (no output schema exists), and it does not name the listing sibling that would be the alternative.

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 and schema coverage is 100%, with the schema itself explaining it is a GUID 'obtained from a preceding read'. The description adds no meaning 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 pairs a generic verb ('Read') with a concrete endpoint ('GET /v1/routes/{id}'), which makes it unambiguously a single-route fetch. The resource is identified only through the URL path, and 'the selected record' is loose phrasing, but combined with the title an agent can distinguish it from servicemonster_list_routes.

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 statement of when to use this instead of servicemonster_list_routes or any other sibling; the only signal is the {id} placeholder implying single-record retrieval. The requirement that an id come from a prior read lives 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, so the safety profile is covered and the bar is lower. Beyond that, the description only restates the GET verb/path and adds nothing about what a missing or unknown id produces, whether the response is a single object, or any auth/rate constraints.

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 waste, but the leading sentence "Read the selected record" is filler that conveys less than the endpoint that follows it. It is concise without being front-loaded with the useful information (that this fetches a service site by GUID).

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?

This is a simple one-parameter read, but there is no output schema, so the agent gets no signal about what a site record contains or how it relates to the account/list siblings. The description leaves both the return shape and the routing decision undocumented.

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

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

Schema description coverage is 100% and the single id parameter is fully documented in the schema, including its UUID format and provenance ("obtained from a preceding read"). The description contributes 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 says "Read the selected record" and gives the HTTP path GET /v1/sites/{id}, which indirectly identifies the resource as a site. But the prose never names the resource itself, so the purpose is only recoverable from the endpoint string and the title. It also doesn't distinguish this from sibling reads like servicemonster_list_sites or servicemonster_list_account_sites.

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

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

There is no guidance on when to use this versus the many sibling list/get tools, no statement that an id from a preceding list call is required, and no exclusions. The agent is left to infer everything from the tool name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful detail that results come back one page at a time and cites the REST path, but says nothing about ordering, page-size defaults, or what happens when filters match nothing.

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

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

Two short clauses with no filler, and the pagination constraint leads. The endpoint reference is arguably redundant given the tool name but is cheap and unambiguous.

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 7-parameter filtered list tool with no output schema, the description never states what a record contains or how filtering and field selection interact. The rich schema compensates for most parameter gaps, but the description leaves the agent guessing about return contents and ordering.

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 limit, pageIndex, fields, wField/wValue and wOperator are already documented in the schema. The description's only contribution is the pagination framing ('one page'), which is already implied by pageIndex; 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 only 'Read one page of related records' — it never names notes or accounts, so the purpose is carried almost entirely by the tool name and title. It does convey the read-many/paginated shape and the underlying endpoint, which distinguishes it from the singular get_note, but only weakly.

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 statement of when to use this versus servicemonster_list_notes, servicemonster_get_note, or servicemonster_list_order_notes. The only implicit guidance is 'one page', which hints at pagination but not at tool selection or prerequisites (e.g. needing a valid account id from a preceding read).

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

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

Annotations already declare readOnlyHint=true and the description is consistent with a safe read. It adds the useful pagination fact ('one page'), which signals the caller must iterate, but says nothing about ordering, default result size beyond the schema, or what a page contains — with annotations covering safety, that is an acceptable but 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?

Two short sentences, front-loaded with the paging behavior and no filler. The trailing raw HTTP path is mildly redundant with the tool identity rather than earning space, which keeps it from a 5.

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

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

With seven parameters, no output schema, and a read-only annotation, the definition is minimal but workable because the schema is fully documented. It stops short of describing the response shape or how to sequence paging against pageIndex, which an agent needs when a result set spans multiple pages.

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 (id, limit, fields, wField/wValue/wOperator, pageIndex) are already documented in the schema. The description adds no extra semantics beyond the implied pagination, 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 title and tool name establish that this lists an account's orders, but the description body only says 'Read one page of related records' without naming the resource. The GET path 'GET /v1/accounts/{id}/orders' implicitly identifies the resource, so an agent can infer the purpose, but it must decode a URL rather than read a stated verb+resource.

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

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

There is no guidance on when to use this versus siblings such as servicemonster_list_orders (global order list) or servicemonster_get_account / servicemonster_get_account_profile. The description gives no conditions, prerequisites, or exclusions to route the agent correctly.

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 still adds genuine value by disclosing that a call returns a single page rather than all matching records, which tells the agent it must paginate to be exhaustive — a behavioral trait not derivable from the annotations.

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

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

Two short sentences, no filler, with the content summary first and the pagination caveat second. Every clause carries information an agent can act on.

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?

Six optional parameters and no output schema, but the schema itself documents each parameter thoroughly and the description covers the key non-obvious behavior (pagination). Only minor gaps remain, such as whether a total count is returned or how filtering interacts with paging.

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 limit, pageIndex, fields, wField, wValue and wOperator all documented in-schema including defaults and pairing constraints. The description adds nothing about parameters, 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 the resource (customer accounts), the returned content (names, contact details, account status), and the underlying endpoint GET /v1/accounts. This clearly reads as a paged collection fetch, distinguishable from get_account, 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?

No statement of when to use this versus get_account or get_account_profile, and no guidance on when filtering with wField/wValue is appropriate. The only usable cue is the 'one page, not all matching records' note, which implies iteration but does not say when this tool is the right choice.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description adds that results are paginated ('one page') and exposes the REST endpoint, but says nothing about total counts, ordering, or what happens when pageIndex exceeds available pages.

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 and the pagination constraint stated up front. It is efficient, though the brevity borders on under-specification rather than tightness.

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

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

With no output schema and seven parameters, the description should at least frame what a page of site records contains or how pagination terminates. It covers the minimum (it's a paged read of a specific endpoint) but leaves the agent guessing about the response shape and total-count semantics.

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 each parameter (limit, pageIndex, fields, wField/wValue/wOperator) is documented in-schema, so the baseline of 3 applies. The description adds no parameter meaning 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?

The description's body says only 'Read one page of related records', which is a generic verb+resource that never names 'sites'; the concrete meaning comes from the endpoint path (GET /v1/accounts/{id}/sites) and the title. An agent can infer purpose, but the prose alone does not distinguish this from list_account_notes, list_account_orders, or list_sites.

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

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

No when-to-use or when-not guidance is given, and no sibling is named. It is unclear from the description why an agent would pick this over list_sites (top-level site listing) or get_site for a single site, leaving selection to inference from the tool name alone.

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

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

The readOnlyHint annotation already establishes this as a safe read operation. The description adds that it returns one page and names the endpoint, but it does not disclose pagination behavior, rate limits, authentication requirements, or what the response contains.

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

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

The description is only two sentences and front-loads the read-page concept before giving the endpoint. It is efficient, though the first sentence is vague enough that not every word carries full informational weight.

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, and the description does not explain return values, pagination mechanics, or how filtering via wField/wValue works. For a seven-parameter list tool, the definition is too thin to fully prepare an agent for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including limit, fields, wField, wValue, pageIndex, and wOperator. The description adds no parameter meaning beyond indicating the id is part of the path.

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 reads 'one page of related records' and gives the endpoint /v1/accounts/{id}/tasks, which implies account tasks. However, 'related records' is vague and it does not distinguish this from sibling list tools such as servicemonster_list_tasks or servicemonster_list_order_tasks.

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 tool versus alternatives like servicemonster_list_tasks, servicemonster_list_order_tasks, or servicemonster_get_account. It also does not state prerequisites or exclusions beyond the endpoint path.

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, and the description adds the non-obvious fact that the call returns only one page rather than all matches, plus the underlying GET /v1/employees endpoint. It stops short of saying how to iterate (the schema's pageIndex does that) or what a page looks like.

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

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

Two short sentences with the purpose first and the pagination caveat second; nothing is wasted. The first sentence is a fragment ('Team members to resolve scheduling employee IDs'), which is terse to the point of slight ambiguity.

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 paged list with a fully documented 6-parameter schema and no output schema, the description covers purpose and the key pagination limitation. Field names or result shape are left implicit, but the schema carries the calling mechanics.

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 limit, fields, wField/wValue and pageIndex is already documented in the schema. The description adds no filtering or paging syntax of its own, 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?

Names the resource (team members / employees) and states the concrete job it serves: resolving scheduling employee IDs. That goes beyond the title 'List employees' and gives an agent a reason to pick it, though it never names a sibling tool it is distinct from.

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 'to resolve scheduling employee IDs', which tells the agent this is an ID-lookup step in a scheduling workflow. There is no explicit statement of when to use something else, or that this reads the raw endpoint rather than a filtered list.

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 context beyond that: the underlying endpoint (GET /v1/jobs) and the important caveat that a call returns one page rather than all matching records, which changes how an agent must loop with pageIndex.

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 and followed by the paging caveat – no filler. The first sentence is a noun fragment rather than a clause, which makes it slightly less scannable than it could be.

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 6-parameter list tool with no output schema, the definition covers returned fields and the paging constraint but leaves open how to retrieve a full result set and how filters combine. The rich schema compensates substantially, keeping this at minimum-viable rather than inadequate.

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 (limit, fields, wField/wValue, pageIndex, wOperator) is already documented with defaults and constraints. The description adds no parameter-level detail such as filter syntax or default page size, 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 names the resource (jobs) and the fields returned (account/order/route IDs, estimated times, status), so the agent knows exactly what comes back. It stops short of distinguishing this from siblings like list_order_jobs or list_job_timelogs, which list subsets of the same records.

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

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

There is no guidance on when to use this versus alternatives such as list_order_jobs (jobs for one order) or get_job (single record). The only usage-adjacent statement is the pagination caveat, which is about mechanics rather than tool 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?

readOnlyHint=true already establishes the safety profile, and the description adds only the notion that results are paginated ('one page'), which is useful but already implied by the pageIndex/limit parameters. It does not disclose ordering, default page size, or what a page 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?

It is short with no bloat, but the first sentence is a vague generic phrase and the second restates the HTTP endpoint, so neither sentence adds much information beyond structured fields. Brevity here comes at the cost of substance rather than through efficiency.

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 paginated list tool with seven parameters, no output schema, and many similar list siblings, the description never explains what a time log record is, how pages should be iterated, or how this differs from other job-related reads. The required job GUID and its 'obtained from a preceding read' dependency are only in the schema.

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

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

Schema coverage is 100%, so all seven parameters (id, limit, fields, wField, wValue, pageIndex, wOperator) are already documented in the schema. The description adds no additional semantics beyond the schema baseline.

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

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

The description says only 'Read one page of related records', which is generic and does not name the resource; only the raw endpoint path '/v1/jobs/{id}/timelogs' reveals it. The title carries the actual meaning, so the description itself is vague about what is being listed beyond it being time logs for a job.

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

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

No guidance on when to use this versus siblings such as servicemonster_get_job, servicemonster_list_jobs, or other list tools. It also doesn't state the prerequisite implied by the required 'id' being a job GUID from a preceding read.

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 meaningful behavioral context beyond that: it discloses the underlying GET /v1/notes endpoint and warns that a single call returns only one page of results, not all matches. It stops short of stating the default page size or what happens with the wField/wValue filters.

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, and the resource scope is front-loaded before the pagination caveat. Slightly too terse for a tool with six parameters and many close siblings, 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?

Given a read-only list tool with a fully documented schema and no output schema, the description covers the resource and the pagination pitfall. It omits the two things an agent most needs here: how this differs from the entity-scoped list siblings, and any hint about the shape of returned notes.

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 are already documented with defaults, bounds, patterns and enum values. The description adds no parameter detail, which the baseline rule permits at 3; a 4 is warranted only because the pagination note reinforces the correct use of limit/pageIndex. This is generous but the schema carries essentially all semantic load.

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 ('Notes attached to accounts, orders and sites') and the endpoint, but uses no explicit verb and never distinguishes this global list from the sibling scoped lists (list_account_notes, list_order_notes, list_site_noteactivities). An agent can guess the scope but must infer whether this is the unfiltered cross-entity 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?

No guidance on when to choose this tool over the scoped siblings or get_note. The only condition-like statement is the pagination caveat, which is about invocation mechanics rather than tool 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?

readOnlyHint=true already declares the safe read profile, so the description's burden is lower. It adds that results are paged ('one page'), which is useful, but says nothing about default ordering, total-count behavior, or what a page contains beyond the endpoint name.

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, and the paging constraint is front-loaded. The trade-off is that the first sentence is so terse it borders on under-specification rather than 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 straightforward paginated read with full schema coverage and a readOnly annotation, no output schema and no nested objects, this is roughly enough to call it. Still missing is any indication of what a 'job' record looks like or how filtering interacts with paging, which would help an agent use it confidently.

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

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

Schema description coverage is 100%, so limit, pageIndex, fields, wField, wValue and wOperator are all documented inline. The description adds only the concept of paging, which the schema already states for pageIndex and limit, 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 prose 'Read one page of related records' is vague about what resource is being read, but the trailing endpoint 'GET /v1/orders/{id}/jobs' pins it down as an order's jobs. It does not explicitly distinguish the tool from the sibling servicemonster_list_jobs (all jobs), leaving the scope contrast implicit.

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

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

No statement of when to use this over servicemonster_list_jobs, get_order, or list_order_tasks, and no prerequisites such as needing an order id from a preceding read. The only implied guidance is that an order id is required, which the schema already enforces.

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

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

The readOnlyHint annotation already establishes the safety profile, and the description reinforces it with 'Read' and a GET endpoint. It also indicates pagination via 'one page', but adds no details about auth, rate limits, or return behavior beyond what the annotation 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 no filler, and the core action is front-loaded before the endpoint. Every sentence contributes directly to identifying the operation.

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 7-parameter read tool with full schema descriptions and a readOnly annotation, the definition is minimally adequate. However, it leaves the return content and pagination behavior mostly to inference and does not compensate for the absence of an output schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the input schema. The description's endpoint mentions the required id in path form but adds no filtering, pagination, or field-selection semantics beyond the schema.

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

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

The description states a read operation and includes the concrete endpoint GET /v1/orders/{id}/lineitems, which identifies the resource as an order's line items. The title and endpoint make it distinguishable from sibling order-related list tools, though the prose itself is terse and relies on the endpoint to carry the resource specificity.

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 to read one page but gives no explicit when-to-use guidance, prerequisites, or alternatives such as get_order or list_orders. The schema notes that id comes from a preceding read, but the description itself does not guide tool 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 declare readOnlyHint=true, so safety is covered. The description adds that results are paginated ('one page'), which is genuinely useful behavior beyond annotations, but says nothing about ordering, default page size behavior, or what a page contains.

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

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

Two short sentences with no filler, and the pagination caveat is stated up front. It is efficient, though the terseness borders on under-specification rather than optimal density.

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 7 parameters, a filter pair (wField/wValue/wOperator), field selection, and no output schema, the description should explain at least that this returns a paginated page of note records filtered to one order. It omits return shape, pagination mechanics beyond 'one page', and how filters interact with the order scope.

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 (id, limit, fields, wField/wValue, pageIndex, wOperator) is already documented in the schema. The description adds no extra meaning about filtering or field selection, 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 says 'Read one page of related records' — the resource is only identifiable from the "GET /v1/orders/{id}/notes" path, not from prose. An agent can infer 'list notes on an order', but the text itself is generic ('related records') and does not name the sibling list_notes or list_account_notes to disambiguate scope.

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 statement of when to use this versus list_account_notes, list_notes, or get_note. There is no guidance on prerequisites (an order id from a preceding read, only hinted at in the schema) and no 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, so safety is covered; the description adds the non-obvious pagination contract ('returns one page, not all matching records') and the endpoint path, which are not in the structured fields. It does not mention ordering, default sort, or whether totals are per-order or aggregate, which would complete the picture.

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, and the pagination limitation is stated up front rather than buried. The first sentence is a verbless fragment, which slightly hurts scannability for an agent parsing intent.

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 six optional parameters, no output schema, and readOnly annotations, the description supplies the two things an agent most needs to know: what the records contain and that a single call is not exhaustive. Ordering/default-sort behavior and the meaning of the returned totals are the only notable omissions.

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 one of the six parameters documented, including the wField/wOperator/wValue relationship and the pageIndex advance hint. The description adds nothing about parameters, 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?

Names the resource precisely (orders) and clarifies what those records include — estimates/invoices plus totals and balance — which an agent can't infer from the tool name alone. It stops short of differentiating from siblings like servicemonster_list_account_orders or servicemonster_get_order, and the opening is a noun fragment rather than an explicit verb.

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

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

The clause 'returns one page, not all matching records' implicitly tells the agent to paginate, which is genuine usage guidance. However, there is no explicit statement of when to pick this over servicemonster_list_account_orders (scoped to one account) or servicemonster_get_order (single record), leaving the sibling routing to inference.

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

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

Annotations already declare readOnlyHint=true, so 'Read one page' merely restates structured data. Pagination behavior is mentioned but is also fully specified by limit and pageIndex in the schema. No auth needs, result shape, ordering, or edge cases are disclosed.

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. However, the brevity comes at the cost of substance — 'related records' is wasted vagueness where a precise noun would have fit equally well.

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 paginated read tool with a fully documented schema and a readOnly annotation, little is strictly required. Still, the description fails to name the returned resource type or clarify that `id` is the order GUID, which is the one thing an agent could get wrong.

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 (id, limit, fields, wField, wValue, pageIndex, wOperator) is already documented in the schema. The description adds no extra meaning about path-parameter binding 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?

The description says 'Read one page of related records' and gives the endpoint GET /v1/orders/{id}/tasks. The endpoint path implies the resource is order tasks, but the prose itself never says 'tasks' or 'related to this order', leaving the resource name to be inferred. Nothing distinguishes it from the many sibling list_* tools (list_account_tasks, list_order_jobs, list_order_notes).

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

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

There is no statement of when to use this tool versus alternatives such as servicemonster_list_tasks or servicemonster_list_account_tasks, nor any prerequisite or exclusion. The only hint is the endpoint path, which an agent must parse and interpret on its own.

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

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

Annotations supply readOnlyHint=true, so safety is covered. The description adds non-obvious behavioral context beyond that: it discloses the HTTP endpoint and warns that the call 'returns one page, not all matching records', which is exactly the pitfall an agent needs to know for a paginated read.

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 pagination caveat is placed last but earns its spot; a slightly more explicit purpose verb would improve the opening.

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 no output schema and fully documented parameters, the description covers the essential caveat (partial results, needing pageIndex advancement) and the endpoint. It omits what a route record contains, but the schema and absence of an output schema make that 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%; limit, pageIndex, wField/wValue/wOperator and fields are all documented in the schema, including the pagination mechanics. The description only indirectly reinforces paging ('one page'), which is baseline for a fully documented schema.

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

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

The description names the resource ('Service routes') and the endpoint GET /v1/routes, making it clear this is a listing operation over routes rather than a single fetch like get_route. It doesn't explicitly contrast with siblings such as list_scheduling or get_route, so it stops short of full 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?

It hints at downstream usage ('their IDs can filter the scheduling view') and implicitly routes the agent away from list_scheduling, but gives no explicit when-to-use/when-not guidance or prerequisites for choosing this over get_route or list_scheduling.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the implicit default date range, the fact that dates are interpreted against the company's scheduling context, and the shape of the returned payload. It omits pagination or result-size limits, keeping 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?

Three short sentences, front-loaded with the endpoint and the default behavior, with no filler. There is a minor typo ('through7days') that slightly hurts readability but no wasted content.

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 two-optional-parameter read tool with no output schema, the description covers the default range, the override mechanism, the date interpretation context, and what is returned. Only pagination/limits and precise date format are left unaddressed, which is a small 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 0%, so the two parameters rely on the description. It explains that startDate/endDate bound the period and that omitting them yields a default window, which is real added meaning. It does not clarify format (date-only vs full timestamp) or inclusive/exclusive boundary behavior, so the compensation is only partial.

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

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

The description names a specific resource (schedule items) and states what is returned: each event plus its associated job/activity/reminder/event details. That is more than a restatement of the title. It does not distinguish itself from the close sibling `servicemonster_list_scheduling`, 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?

It states the default window (today through 7 days ahead) and that startDate/endDate should be used for a bounded period, which implies when to supply parameters. However, it gives no guidance on when to pick this tool over `list_scheduling` or `list_jobs`, and no exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior: the implicit default date window when no dates are passed, the fact that dates resolve against the company's scheduling context, and that results are a flattened event view rather than raw records. It omits pagination/result-size limits, which matter for a list endpoint over a date range.

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

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

Four terse sentences, front-loaded with the endpoint and default window before the parameter and output notes. A typo ('through7days') and the raw REST path are minor noise, but 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 read-only list tool with an output-shape note this covers the essentials, but with 4 params at 25% coverage and no output schema, the unexplained getJobColor and the absence of any guidance versus the scheduleitems/routes siblings leave real gaps.

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

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

Schema coverage is only 25% — routeID is documented, startDate/endDate/getJobColor are not. The description compensates for the date pair (bounded period, company scheduling-context semantics) and hints at routeID ('optionally one route'), but getJobColor is left entirely unexplained in both schema and description.

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

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

States a specific verb+resource pair (read the service schedule / GET /v1/scheduling) and adds output-shape context ('flattened event view, optionally one route') that hints at how it differs from list_scheduleitems or list_routes. It never names those siblings explicitly, so the differentiation is implied 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?

Gives concrete usage context: the default window is today through 7 days ahead, and startDate/endDate should be supplied for a bounded period. It does not say when to prefer this over list_scheduleitems, list_routes, or get_route, and gives no 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, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses that the call returns a single page and will NOT return all matching records, which is the key trap an agent must handle via pageIndex.

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 resource and followed immediately by the pagination caveat. Minimal waste, though the raw 'GET /v1/serviceitems' fragment adds little for an agent and the second clause is compressed to the point of being clipped.

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 6 optional params fully documented and no output schema, the description covers pagination behavior but says nothing about the shape or contents of a service item record or which fields are valid for 'fields'/'wField'. An agent knows how to page but not what it will get back.

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 (limit, fields, wField/wValue, pageIndex, wOperator) is already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource: retrieving the company's service-item catalogue, with the underlying endpoint. The resource is unique among siblings (no other service-item tool exists), so disambiguation is not needed, but the description never explicitly says 'list' or how it differs from the get_* family.

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

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

Usage is only implied by the phrase 'catalogue' plus the pagination warning; there is no explicit when-to-use, when-not, or prerequisite guidance (e.g. auth, whether this is the only way to enumerate service items before calling create_note with a service item reference).

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 only added behavior — 'one page' — hints at pagination without explaining how to advance (schema's pageIndex does), and nothing is said about ordering, total counts, or the shape of returned note activities.

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, so there is no bloat, and the read scope is front-loaded. However, the second sentence is a raw endpoint path that restates the resource the first sentence failed to name, making the text efficient but not informative.

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 7-parameter list tool with no output schema needs the description to explain what a note activity is, how it relates to notes and sites, and how paging/filtering is expected to be used. The description covers none of this, leaving the agent dependent entirely on 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%, including id provenance, limit, fields projection, wField/wValue/wOperator filtering, and pageIndex semantics, so the baseline is 3. The description adds no parameter meaning beyond that; 'one page' weakly echoes pageIndex/limit but supplies no format or usage detail.

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 only 'Read one page of related records', which never identifies the resource as a site's note activities; that only appears in the title. An agent reading the description alone cannot tell this apart from any of the ~25 sibling list_* tools.

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

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

No when-to-use guidance and no comparison to alternatives such as servicemonster_list_notes, servicemonster_list_account_notes, or servicemonster_get_site. Nothing indicates whether a site id from a preceding read is required versus other note-listing routes.

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds one genuinely useful behavioral fact: the call returns a single page rather than all matching records, which prevents an agent from treating a short result as complete. It adds nothing about auth, ordering, rate limits, or which fields come back.

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, no filler, with the page-size caveat given equal prominence to the resource description. Slightly clipped phrasing ('GET /v1/sites') is efficient 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?

For a six-parameter list tool with no output schema and no required parameters, calling it correctly is mostly covered by the schema plus the read-only hint. What is missing is what a result record contains and how to exhaust the full result set beyond 'advance pageIndex', which the schema only hints at.

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

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

Schema description coverage is 100%, with limit, fields, wField, wValue, pageIndex and wOperator all documented inline including the wField/wValue pairing and the 'like' substring behavior. The description adds no parameter meaning beyond that, 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?

Names the resource concretely (customer service locations and their addresses) and pins it to an endpoint, so an agent knows it is a site listing rather than a detail fetch. It does not distinguish itself from siblings like servicemonster_list_account_sites or servicemonster_get_site, which is the one missing piece for 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?

There is no guidance on when to choose this over servicemonster_list_account_sites (scoped to an account) or servicemonster_get_site (single record), nor on when to use the wField/wValue filters versus paging the whole set. The pagination remark describes behavior, not tool 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by warning that it "returns one page, not all matching records" and naming the endpoint, but it does not describe the response shape, default ordering, or pagination beyond what the schema already documents for pageIndex.

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 short and front-loads the pagination limitation. However, the opening fragment "Tasks;" is awkward and slightly under-specified rather than maximally informative.

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 list tool with full schema coverage and a readOnly annotation, the description covers the key pagination caveat. It remains incomplete in that there is no output schema and the description does not characterize what a task record contains or how the returned fields map to assignments and follow-ups.

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 wField, wValue, wOperator, fields, limit, and pageIndex are already documented in the schema. The description adds no parameter-level meaning beyond that, which is acceptable but not additive.

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 "Tasks" and references the GET /v1/tasks endpoint, which implies listing tasks, but it does not use a clear verb+resource phrase and does not distinguish this generic task list from siblings like servicemonster_list_account_tasks or servicemonster_list_order_tasks.

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 suggests using returned fields to inspect assignments and follow-ups, but gives no explicit when-to-use guidance, no prerequisites, and no indication of when to prefer the account-specific, order-specific, or job-specific task list siblings.

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