UpKeep MCP by usefulapi

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

Goes beyond annotations in two meaningful ways: it clarifies that a reading is permanent and cannot be removed with this server, and that a meter notification may auto-create a work order when its condition is met — a downstream side effect the agent could not infer from destructiveHint/openWorldHint alone. It does not mention retry behavior, though idempotentHint=false makes duplicates a real risk worth flagging.

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 operation type front-loaded and the consequential facts following. No filler text.

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

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

A three-parameter write tool with full schema coverage and clear annotations is well served by this description: creation semantics, irreversibility, and automated work-order side effects are all covered. The only gap is that, with no output schema, it never says what the call returns (presumably the created reading).

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema itself; the description adds no syntax or constraint detail. The embedded endpoint path POST /meters/{id}/readings is marginally useful but not new parameter meaning.

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

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

States a specific verb and resource ("record a new reading on a meter") and grounds it with concrete examples of reading types. The "WRITE:" prefix immediately separates it from read-only siblings such as upkeep_list_meter_readings or upkeep_get_meter.

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 WRITE marker and side-effect notes imply this is the creation path, but the description never names an alternative or states when not to use it (e.g. versus upkeep_list_meter_readings or update tools). Usage is inferable rather than explicit.

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

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

Annotations already declare destructiveHint, openWorldHint, and non-idempotent. The description adds a meaningful behavioral fact not in annotations: 'people following the work order may be notified', surfacing a side effect the agent should anticipate. It doesn't cover irreversibility or failure modes, 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?

A single tight sentence plus endpoint, with the WRITE mutation type front-loaded. No wasted words.

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

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

For a simple 2-required-param mutation with full schema coverage and rich annotations, the description covers action, side effect, and endpoint adequately. No output schema exists, so return-value explanation isn't expected; error/permission behavior is the only minor gap.

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

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

Schema description coverage is 100%, so both parameters (work_order_id, text) are well documented in the schema. The description adds no syntax or format meaning beyond the endpoint path implying the id, 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 (post a message/comment) and resource (work order activity thread), and the endpoint POST /work-orders/{id}/update-messages nails the scope. It's clearly distinguishable from siblings like upkeep_update_work_order or upkeep_create_work_order, which mutate fields rather than append a comment.

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 'WRITE:' prefix signals this is a mutation, and 'post a message on a work order's activity thread' implies the use case. However, it never states when to use this vs alternatives or any prerequisites (e.g., must the work order exist/be open), leaving guidance implicit.

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 destructive/non-idempotent/open-world, and the description adds real context beyond them: the state transition into a work order, a possible assignee notification, a required privileged role, and the exact 409 conflict condition. It stops short of saying whether approval can be undone or what is returned, which matters given destructiveHint=true.

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

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

Three tight sentences with the write/approve intent front-loaded, followed by side effects, auth requirement, error case, and endpoint. Every sentence carries distinct information; nothing is redundant.

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

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

For a one-parameter mutation with no output schema, it covers auth, side effects, and failure semantics well. The remaining gap is the return value — since approval produces a new work order, an agent would benefit from knowing whether the new order id comes back or a follow-up lookup is needed.

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 request_id parameter is fully documented in the schema with an example id format. The description adds only the endpoint template POST /requests/{id}/approve, which confirms path placement but no new syntax or constraints, so the baseline 3 applies.

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

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

The description opens with an explicit verb and resource ("WRITE: approve a pending work request") and immediately names the resulting state change ("converts it into a work order"), which no sibling tool does. An agent can distinguish this from upkeep_create_work_order or upkeep_get_request without inspecting either schema.

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

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

It gives a clear condition for calling (a request must be pending) and states the failure mode when that condition is violated (HTTP 409 on already-approved or declined). It does not explicitly name an alternative such as checking status via upkeep_get_request first, so the routing guidance is implicit rather than complete.

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?

Beyond annotations, the description discloses that the request may notify approvers or the assignee and that it remains a request until approved. That adds useful side-effect and lifecycle context, though it does not discuss permission or rate-limit 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?

The description is three tight sentences, front-loaded with “WRITE,” and contains no wasted text. It moves cleanly from purpose to lifecycle to form-specific input guidance.

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

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

For a 10-parameter create tool with no output schema, the description gives enough context to call it safely: request lifecycle, side effects, and `fields` behavior. It could say more about the response or approval implications, but annotations and schema cover most remaining details.

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

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

Schema coverage is already high at 90%, so the schema carries most parameter meanings. The description adds useful conditional guidance for `fields`, explaining that field labels from the account’s request form should be used when such a form is configured.

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 uses a specific verb and resource: “submit a new work request.” It also distinguishes the object from a work order by stating “It is not a work order until approved,” which helps separate it from sibling creation tools.

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

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

It explains the tool’s context clearly: submitting a request for maintenance-team approval, with the result appearing in the Requests list. It does not explicitly say when to use create_work_order or approve_request instead, so the alternative-routing guidance 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 write/destructive/non-idempotent/open-world, so the bar is lower; the description still adds real side-effect context — the assignee may be notified and the record appears on the work order board — plus the underlying endpoint. It does not state permissions required or what happens on duplicate submission (relevant given idempotentHint=false).

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

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

Two sentences, with the operation class and side effects front-loaded before the endpoint reference. No filler or restatement 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 10-parameter mutation tool with no output schema, it covers the key unknowns: side effects, id sourcing, and the underlying API call. What is returned (e.g. the new work order id) is not mentioned, which is a modest gap for a create operation an agent may need to chain on.

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 80%, so the schema largely documents itself; the description adds value by clarifying that asset, location and assignee are foreign ids sourced from list tools, which the schema labels only as 'Asset id.', 'Location id.', 'User id to assign.' The remaining params (category, priority, dates) are left to 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 opens with a specific verb+resource ('create a new work order') and labels the operation class ('WRITE:'), which clearly separates it from upkeep_update_work_order and the read siblings. It stops short of naming the nearest alternative (upkeep_create_request), so the distinction from that sibling must be inferred.

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?

'Ids for asset, location and assignee come from the list tools' is a concrete prerequisite that routes the agent to upkeep_list_assets / upkeep_list_locations / upkeep_list_users before calling. There is no explicit when-not guidance (e.g. when to use create_request instead), so it is clear context but not full 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 and destructiveHint=false, so the description is not the only source of safety information. It adds value beyond them by naming the underlying GET endpoint and describing the exact response fields, though it says nothing about rate limits or what is returned (or thrown) when the token is invalid or expired.

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

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

Two sentences, front-loaded with the purpose, followed by the returned fields and the raw endpoint. Every clause carries information and 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?

With no parameters and no output schema, the description carries the return-value burden and does so by listing the four fields. It falls slightly short of complete because the failure mode (inactive/expired token) is not described, which is the main scenario an agent would be checking for.

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 there is nothing for the description to disambiguate; baseline is 4. The description correctly conveys that no input is required.

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 specific verb (confirm/check) with a specific resource (the UpKeep API token) and enumerates exactly what is returned: company id, token name, creation and last-used timestamps. It is unambiguous and cannot be confused with any sibling list/get tool, which all operate on domain entities like work orders or assets.

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 purpose — verifying that a token is active — implies when an agent should reach for it (before other calls, or when diagnosing auth failures), but that is left for inference. There is no explicit statement of when to use it, when not to, or what a sibling alternative would be.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by saying related records such as users, teams, vendors, parts, files, and sub-assets are optional inclusions, though it does not mention not-found behavior or permission requirements.

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

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

The definition is a single front-loaded sentence followed by the endpoint. It is appropriately sized for a get-by-id tool and contains no redundant or filler 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?

With no output schema, the description usefully summarizes what the response contains: purchase and warranty details, custom fields, and optional related records. It is largely complete for this read operation, though minor operational details such as not-found handling are not covered.

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

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

Schema description coverage is 100%, so both asset_id and includes are already documented in the schema. The description mentions optional related records but does not expand on the full allowed includes list or add meaning beyond the schema's own explanation.

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 it returns one asset by id and enumerates the included details, with the endpoint GET /assets/{id} making the retrieve operation explicit. The singular-by-id scope distinguishes it from sibling list_assets, so an agent can tell what resource and cardinality to expect.

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

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

The phrase 'by id' implies the tool is used when an asset id is already known, which is useful context. However, it does not explicitly say when to use this versus upkeep_list_assets or how to find an id first, so usage guidance is mostly implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds only the REST path GET /locations/{id}, with no mention of behavior on missing/invalid ids or permissions.

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

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

Two short sentences, front-loaded with the resource scope and zero filler. It is terse to the point of near under-specification, 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?

For a single-param read with full schema coverage and annotations carrying the safety profile, the description is adequate but bare. It could cheaply add the id-then-fetch usage cue that would help an agent choose it over the 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 coverage is 100% and the single location_id param is documented with type, length bounds and an example format ("HW2I379ErS"). The description adds nothing beyond "by id," 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?

"One location by id" states a specific resource and the single-record scope, which implicitly distinguishes it from upkeep_list_locations. It is clear but never names that sibling to make the differentiation explicit.

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

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

No guidance on when to use this versus upkeep_list_locations (e.g. when you already have an id rather than needing to search). The only usage signal is the implicit "by id," leaving the choice to the agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing behavioral beyond restating the HTTP verb/path — no note on what happens for an unknown id, error behavior, or response shape.

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

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

Two short telegraphic fragments with zero padding, resource scope front-loaded. It leans toward under-specification rather than verbosity, 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?

For a single-parameter read tool with full schema coverage and safety annotations, the essentials are present. It stops short of stating that it returns a single meter object or how a missing id behaves, which would fully round it out.

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 meter_id parameter carries its own description with a concrete example format. The description's "by id" merely echoes that; baseline 3 is appropriate when 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?

"One meter by id" plus the REST path GET /meters/{id} identifies a singular fetch of the meter resource unambiguously. It does not name upkeep_list_meters as the alternative, so sibling differentiation is only implicit through the singular phrasing.

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 upkeep_list_meters or upkeep_list_meter_readings, and no preconditions. The agent must infer usage purely from the singular noun and the path template.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds the data returned (quantity, cost, location, custom fields) and names the underlying GET endpoint, though it says nothing about behavior when the id is not found.

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 are front-loaded with the core purpose and returned fields. The 'GET /parts/{id}' sentence is mildly redundant with the annotations and title but does not obstruct the description.

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 annotations covering safety and no output schema, the description supplies the returned field list that would otherwise be missing. Only edge-case behavior (e.g., unknown id) is left unaddressed, which is minor for this complexity level.

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 an example id format, so the schema already fully documents the single part_id parameter. The description's 'by id' adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('One part by id') and implicitly distinguishes itself from upkeep_list_parts by scoping to a single id. It does not explicitly name sibling alternatives, so it stops short of the top score.

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' suggests it is the tool to call when the part id is already known, but the description never says when to prefer it over upkeep_list_parts or upkeep_update_part_quantity. 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful information by enumerating what the response contains, compensating partially for the absent output schema, but says nothing about not-found behavior or permissions.

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

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

Two short sentences with zero filler: the returned content is front-loaded and the endpoint path follows as a compact locator. Nothing could be removed without loss.

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 full annotation coverage and no output schema, the description is nearly sufficient because it enumerates the returned fields. Only the failure/empty case is left 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 parameter's schema entry already gives the id format and an example ('HW2I379ErS'). The description's 'by id' 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?

States a specific verb and resource ('One purchase order by id') plus the payload it returns (parts, quantities, costs, shipping details). The word 'One' implicitly contrasts with the sibling upkeep_list_purchase_orders, but that 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?

Usage is only implied: retrieve a single PO when you have an id. There is no explicit statement of when to prefer this over upkeep_list_purchase_orders, nor any note about behavior when the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds real value by disclosing return semantics, notably that the linked work order id exists only 'once approved', telling the agent the field can be absent — context the annotations cannot convey.

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 compact sentence front-loads the resource and scope before listing payload contents, followed by the endpoint. No filler.

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

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

With no output schema, the description does a good job sketching the return shape (form fields, conditional work order id) for a tool signature this simple. Minor gaps remain: nothing on not-found behavior or whether form fields are always present, but nothing essential to calling it is missing.

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

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

Schema coverage is 100% and the schema documents request_id with an example format, so the parameter burden is already handled. The description only repeats 'by id' and adds no format or lookup guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb (get), resource (work request), and scope (one by id), plus what the payload contains: form fields and the linked work order id. That distinguishes it from upkeep_list_requests and from upkeep_get_work_order without needing the schema.

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

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

The 'by id' phrasing implies this is the single-record lookup, but it never states when to use it over upkeep_list_requests, nor that you need an id obtained elsewhere. 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description contributes only the REST endpoint mapping; it says nothing about missing-id/404 behavior, auth requirements, or whether the response includes expanded relations.

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 telegraphic fragments with zero waste and the key semantics front-loaded. It is compact to the point of being skeletal, but nothing is redundant.

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

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

For a single-parameter, read-only getter with full schema coverage and annotations covering the safety profile, this is close to sufficient. Only failure-mode and response-shape context is absent, which is minor given no output schema expectation.

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 user_id parameter is documented in-schema with an example format. The description reinforces that the id is the sole lookup key ('by id') but adds no format detail beyond the schema.

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

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

States a specific verb (get) and resource (user) plus the lookup key (id), and the endpoint mapping confirms it is a single-record fetch. It implicitly contrasts with upkeep_list_users but 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?

'One user by id' implies use when a single known id is available, so usage is inferable rather than stated. There is no explicit when-not guidance or pointer to upkeep_list_users for discovery-type lookups.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open world), so the description only needs to add context. It adds the payload contents, but says nothing about error behavior for unknown ids, permissions, or how the 'includes' expansion changes the shape of results — a notable gap for a tool whose whole point is fetching a rich record.

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

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

Two tight sentences with zero waste; the returned contents are front-loaded and the endpoint path is a compact trailing reference. Nothing is repeated 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 no output schema, the description does the work of telling the agent what comes back, which is the key missing piece. It stops short of explaining how the optional includes parameter modifies the response, but the schema covers that field, so the definition is close to 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 coverage is 100%, so both parameters (work_order_id and includes) are documented in the schema itself. The description adds no format, example, or guidance about the optional includes expansion, leaving the schema to do all the work — the baseline 3 applies.

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

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

The description names a specific verb ('Get') and resource ('One work order by id') and enumerates the sub-resources returned (checklist items, custom fields, time log, parts, files). The 'by id' phrasing implicitly separates it from upkeep_list_work_orders, though it never names that sibling explicitly.

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

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

Usage is only implied: 'by id' suggests you need a known identifier, which contrasts with the list tool. There is no explicit statement of when to prefer this over upkeep_list_work_orders or when to follow up with upkeep_update_work_order.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. Beyond that, the description adds value by enumerating the returned fields (name, model, serial, barcode, location, status, downtime status, warranty, open work order count) and naming the underlying endpoint GET /assets — important because there is no output schema. It does not mention pagination behavior or result limits.

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

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

Two tight sentences, front-loaded with the resource and returned fields before the filter list. The filter enumeration partly duplicates the schema, which is the only wasted space.

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

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

For a 16-parameter, zero-required list tool with no output schema, the description supplies the returned-field inventory that the schema cannot and points at the endpoint. Gaps remain around pagination (limit/offset/next_offset workflow) and the 'includes' expansion, which the description never mentions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates a subset of the filterable fields (name, serial, barcode, location, status, category, assignee) and omits pagination, includes, order_by, downtime_status and the date-range filters, so it adds little beyond the schema.

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

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

States a clear verb+resource ('List assets (equipment)') and enumerates the fields returned plus the filterable fields, so the agent knows exactly what this tool surfaces. It does not explicitly contrast with the sibling upkeep_get_asset or the other list_* tools, 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 implied by the word 'List' and the filter list, from which an agent can infer 'use this to browse/search assets'. There is no explicit when-to-use guidance, no statement that this is the bulk alternative to upkeep_get_asset for single-record lookups, 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that it returns contact details and uses GET /customers; it does not mention pagination behavior or response shape beyond contact details.

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

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

Two short sentences, front-loaded with the core purpose and ending with the endpoint. There is no wasted text.

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

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

For a simple read-only list tool with rich annotations and fully documented parameters, the description is complete enough to invoke correctly. It could be stronger by hinting at pagination or the broader returned fields, but nothing critical is missing.

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

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

Schema coverage is 100%, and the schema fully documents the name filter, limit, and offset. The description adds no syntax or filtering semantics beyond the entity definition, so the 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 ('List') and resource ('customers'), and clarifies the entity as parties whose assets or locations you maintain. It is clear, though it does not explicitly differentiate from other list endpoints such as vendors or locations.

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 tool versus alternatives, no mention of prerequisites, and no exclusions. The implied usage is simply to browse customer records.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint mapping (GET /locations) and the returned fields; it says nothing about pagination behavior, result volume, or permission requirements beyond what the schema implies.

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 padding. The trailing "GET /locations" is low-value REST trivia but costs almost nothing.

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

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

For a 12-parameter read-only list tool with full schema coverage and explicit annotations, the description gives enough to call it correctly — the returned field set is enumerated and the resource is scoped. The only gap is that its substantial filtering capability is never hinted at in prose.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not explain any parameter — no mention of name/barcode exact-match filtering, date-range filtering, hierarchy_level, includes expansion, or order_by defaults — leaving all semantics to the schema.

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

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

States a specific verb and resource ("List locations") and disambiguates the domain term with concrete examples (sites, buildings, rooms) plus the fields returned. It doesn't explicitly distinguish itself from upkeep_get_location or upkeep_list_assets, but the resource is unambiguous against the 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?

Listing is self-evident from the name "List locations", and the parenthetical clarifies what counts as a location. However, there is no statement of when to use this versus upkeep_get_location (single record) or when to reach for upkeep_list_assets instead, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the default result ordering and the shape of returned records, but says nothing about pagination behavior, rate limits, or what happens for a meter with no readings.

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: what you get, what identifies it, and the ordering all come first, and the raw endpoint is relegated to the tail. No sentence is wasted.

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

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

With no output schema, the parenthetical describing returned fields (value, date, who recorded it) fills the main gap, and the schema covers paging and filtering. Only a note on empty results or cross-referencing upkeep_get_meter is missing.

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

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

Schema description coverage is 100%, with limit, offset, order_by and the read_after/read_before date bounds all documented inline, so the baseline is 3. The description adds no extra meaning to those parameters — 'newest first' merely restates the order_by default already in the schema.

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

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

Names a specific verb and resource (readings for one meter) and scopes it to a single meter, plus previews the returned fields and sort order. It doesn't explicitly contrast with the write sibling upkeep_add_meter_reading or with upkeep_get_meter, leaving some differentiation 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?

The description implies the context of use by requiring a meter id and stating results are newest first, but it never says when to pick this over upkeep_get_meter or upkeep_add_meter_reading, nor any prerequisites for the meter existing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint and what a meter record carries (units, reading frequency, owning asset/location), but says nothing about pagination behavior, result caps, or auth scope beyond what the limit/offset schema already implies.

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

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

Two sentences, front-loaded with the purpose, the parenthetical clarifying what a meter is, and the endpoint. No filler or redundancy.

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 11 optional parameters and no output schema, the description should carry more of the return-shape and pagination story. It describes the record contents reasonably but omits paging/next_offset behavior and total counts, leaving gaps for an agent assembling a listing call.

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

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

Schema description coverage is 100% across all 11 parameters, so the schema fully documents filtering, includes expansion, ordering and date bounds. The description only alludes to the returned attributes and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (meters), and even disambiguates the domain concept with examples (hours, mileage, temperature) plus the fields returned. It implicitly separates itself from upkeep_get_meter and upkeep_list_meter_readings, but 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?

Usage is only implied by the noun 'List' and the GET /meters endpoint reference. There is no statement about when to prefer this over upkeep_get_meter for a single meter or upkeep_list_meter_readings for readings, and no exclusions or prerequisites 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context by listing returned fields and explaining the reorder comparison, without contradicting 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?

The description is front-loaded with the core action and returned fields, followed by a practical usage note and endpoint. There is no redundant or filler 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?

Given the full schema coverage and existing annotations, the description is largely complete for a list tool: it explains purpose, returned fields, and one key use case. It could mention pagination or filtering more explicitly, but the schema already carries that detail.

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 12 parameters are already documented in the schema. The description names category, location, and part number but does not add filter semantics or explain limit, offset, includes, order_by, or date parameters beyond what the schema provides.

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

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

States a specific verb and resource ("List spare parts") and identifies the returned attributes, making it clearly distinguishable from the singular sibling upkeep_get_part and from non-inventory 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?

Provides a clear usage context: compare quantity with minimumQuantity to find parts to reorder. It does not explicitly name alternatives such as upkeep_get_part or state when not to use this tool, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes real behavioral detail beyond the annotations: 1-based paging, the GET /pm endpoint, and that schedules are only returned when requested. It does not mention pagination totals or default page size, leaving some gaps.

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

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

Three sentences, front-loaded with what the resource is, then filters, then paging rule, then the upstream endpoint. Every sentence carries information an agent can act on; nothing is repeated verbatim from the schema.

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

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

For a read-only list tool with 9 optional params and no output schema, the description covers purpose, filters and paging adequately. Missing are response-shape hints (totals, ordering, default page size) that an agent would need to iterate pages, though these are minor for a list call.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by naming the filterable dimensions (text, asset, location, assignee, team, priority) and stating pages are 1-based, which reinforces the schema's exclusiveMinimum constraint. It doesn't add format detail beyond the schema, so not a 5.

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

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

Specific verb (List) plus a precise resource (preventive maintenance templates that generate scheduled work orders) with their schedules. The parenthetical explanation distinguishes PMs from the sibling upkeep_list_work_orders by clarifying PMs are the recurring templates, not the generated 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?

Usage is implied by the filter list and the endpoint reference, but there is no explicit when-to-use / when-not-to-use guidance nor a pointer to the sibling (e.g. upkeep_list_work_orders for instances vs. templates). The agent must infer the split from the description 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by enumerating what comes back (status, vendor, dates, total cost, quantities) in the absence of an output schema, but says nothing about page size defaults, next_offset looping, or result caps 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 tight sentences, front-loaded with the resource and return fields, with the endpoint as a trailing anchor. No filler, though the brevity borders on under-specification for a 14-parameter tool.

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

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

With 14 optional params, no output schema, and read-only annotations, the description is only minimally adequate: it tells the agent what a record looks like but not how to page, what defaults apply, or how filters combine. The filtering dimension is left entirely to the schema.

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

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

Schema coverage is 100%, so all 14 parameters are already documented with limits, enums, and patterns. The description only echoes a subset (status, vendor, dates), adding no semantics beyond the schema and omitting mention of order_by, includes, title, or category.

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 ('purchase orders'), plus a compact inventory of the fields each record carries (status, vendor, dates, cost, quantities) and the backing endpoint. It distinguishes itself from the singular sibling upkeep_get_purchase_order through the list semantics, though it never names that sibling explicitly.

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

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

Usage is only implied: an agent can infer 'use this to enumerate/filter POs, use get_purchase_order for one'. There is no explicit when-to-use/when-not, no guidance on combining filters, and no pointer to the single-record sibling or to pagination strategy.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful domain context (these are portal/staff requests not yet converted, endpoint GET /requests) but says nothing about result volume, pagination behavior, or that includes expands referenced ids inline.

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

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

One sentence plus the endpoint path — no padding, and the resource and lifecycle qualifier are front-loaded. The parenthetical is doing real work; the trailing "GET /requests" is slightly redundant but harmless.

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

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

For a 16-parameter read-only list tool with no output schema, the description covers the domain meaning of the resource and relies entirely on the schema for filters, sorting, and pagination. That is defensible given 100% coverage, but the incorrect status vocabulary is a real correctness gap, and there is no word on page limits (1-100) or what comes 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 all 16 parameters are already documented, which would normally justify a 3. But the description actively misinforms about the most important filter it mentions: it lists statuses "open/approved/rejected" while the request_status enum is requested/declined/approved. An agent taking the description at face value would pass an invalid enum value; the rest of the parameters get no description-level elaboration.

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?

Clear specific verb and resource ("List work requests") plus the lifecycle position: pre-work-order, submitted by staff or the request portal. That distinguishes it from list_work_orders and get_request without the agent opening a schema. However, the stated statuses ("open/approved/rejected") do not match the actual request_status enum, which muddies the resource definition.

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 "before they become work orders" implicitly tells the agent this is the pre-conversion queue and hints that list_work_orders is the post-conversion counterpart, but it never says so explicitly. There is no when-not guidance, no mention of get_request for a single item, and no note about which filters matter most.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a small amount by naming the return fields (name and description) and the HTTP endpoint, but says nothing about pagination behavior or result ordering.

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

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

Three short, front-loaded fragments with no filler: purpose, usage hint, endpoint. Nothing extraneous, though it is terse to the point of thinness.

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

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

With no output schema, the description should signal the return shape, and it does ('name and description'). Pagination is handled in the schema's next_offset note, so the definition is adequate for a simple filtered-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 name, limit, and offset are fully documented in the schema, including the next_offset hint. The description adds no parameter meaning beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource: 'List teams with name and description' plus the endpoint GET /teams. It is clearly distinguishable from sibling list_* tools by resource, though it does not explicitly differentiate itself from them.

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

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

'Use the ids to assign work' hints at a downstream use case, implying when the tool is useful. However, there is no explicit when-to-use vs when-not guidance or naming of alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description earns credit by disclosing the returned attributes (account type, job title, status, last login) and the underlying GET /users endpoint, which matters since there is no output schema; it omits any mention of pagination limits or auth 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 short sentences, front-loaded with what is returned and followed by the practical use of the ids. No filler or redundancy with 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?

With nine optional filters fully documented in schema and safety fully covered by annotations, the description's remaining job is telling the agent what comes back and why it cares — which it does via the field list and the work-order assignment hint. Only return-shape detail and paging expectations are left implicit.

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 enum values for account_type and paging semantics for limit/offset, so the schema carries parameter meaning. The description adds nothing param-specific beyond naming the account-type concept, 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 UpKeep users') plus the concrete population it returns (technicians, admins, requesters) and the useful fields. The verb 'List' paired with the sibling 'upkeep_get_user' makes the retrieve-one vs. retrieve-many split unambiguous.

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

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

'Use the ids to assign work orders' gives one concrete downstream use, which is real guidance beyond the name. However, it never says when to prefer upkeep_get_user for a single lookup or when to page instead of filtering, so alternatives remain implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results include contact details and cites the underlying endpoint (GET /vendors), which is mild extra context, but it says nothing about pagination behavior or result size, which matters for a paged 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 waste, with the resource definition front-loaded. It is perhaps too terse rather than padded, so the only deduction is that it under-delivers on guidance.

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 three-optional-parameter read tool with a fully documented schema and clear read-only annotations, the essentials are present. However, the description does not indicate whether the list is scoped to the account, how large result sets behave across pages, or what fields 'contact details' covers, leaving modest gaps.

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

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

Schema description coverage is 100%: limit, offset, and business_name are each fully documented, including the hint to pass next_offset from the prior reply. The description adds nothing 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 ('List vendors') and disambiguates the term by naming 'suppliers and contractors'. It does not distinguish itself from siblings such as upkeep_list_customers or explain why one would list vendors rather than customers, but the resource is unambiguous.

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

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

The description only says what the tool does; it gives no when-to-use context, no prerequisites, and no mention of alternatives among the many list_* siblings. An agent must infer that this is the entry point for browsing vendors rather than searching for a specific one.

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

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

Annotations already cover the read-only, non-destructive, open-world safety profile. The description adds useful context beyond that: default newest-first ordering, returned work-order fields, and the breadth of available 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 sentences, front-loaded with what the tool returns and followed by what can be filtered. There is no wasted wording.

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 list tool with 23 parameters, no output schema, and rich annotations, the description is largely complete: it names returned fields and filter dimensions. Pagination and inline expansion via includes are left entirely to the schema, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all 23 parameters thoroughly. The description summarizes filter categories but does not add syntax or behavioral meaning beyond what the schema provides, making 3 the appropriate 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 gives a specific verb and resource — listing work orders — and clarifies that both reactive and preventive work orders are included. It does not explicitly differentiate from siblings like upkeep_get_work_order or upkeep_list_preventive_maintenance, 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 implies usage through filterable fields and a GET endpoint, but never states when to use this tool versus upkeep_get_work_order or upkeep_list_preventive_maintenance. There is no explicit when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description earns credit by explaining *why* — this is an absolute overwrite, not a delta, which directly explains the idempotency and makes the destructive behavior concrete. It leaves out auth/permission needs and whether a low-stock notification fires immediately, so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with the 'WRITE:' signal and the overwrite rule, with zero filler. Every sentence carries operational value.

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

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

For a three-parameter mutation with full schema coverage and clear annotations, the description covers the essential risk (overwrite semantics). It does not say whether the updated part is returned or what happens with an invalid part_id, minor gaps given no output schema exists.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including 'quantity' as 'a total' and 'minimum_quantity' as the low-stock threshold. The description reinforces the total-vs-difference distinction but adds little new per-parameter meaning beyond what the schema 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 names a specific verb+resource ('set the quantity on hand ... of a part') and scopes the optional low-stock threshold explicitly. The 'WRITE:' prefix and 'PATCH /parts/{id}' immediately separate it from the read-only siblings like upkeep_get_part and upkeep_list_parts.

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

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

It gives a concrete precondition — 'read the part first' — routing the agent to upkeep_get_part before calling, and explains what value to pass. It does not state any when-not-to-use case, but the usage context is clear and actionable.

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=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them: merge-vs-replace semantics and the non-obvious side effect that completing a work order may fire integrations such as Zapier. It omits permission requirements and whether the response returns the updated record, keeping it below a 5.

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

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

Four tight sentences, front-loaded with a 'WRITE:' marker and the resource, then semantics, then side effects, then scope limits. No sentence restates the name or wastes tokens.

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 mutation with no output schema, the description covers the mutation model, side effects, and what the tool cannot do. The only remaining gap is auth/permission expectations and failure behavior, which is minor given well-documented params.

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 57%, so the schema documents the tricky params (due_date ISO 8601, priority scale, work_order_id format) itself. The description mirrors the mutable field list and repeats the status enum but adds no format or constraint detail beyond what is already structured, 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 (change fields of an existing work order), enumerates exactly which fields are mutable, and names the HTTP verb/path (PATCH /work-orders/{id}). This clearly separates it from upkeep_create_work_order and upkeep_get_work_order without the agent opening a schema.

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

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

Gives clear operating context: partial-update semantics ('Only the fields you pass change') and an explicit exclusion ('Archiving and deleting are not offered'). It stops short of naming the sibling tool that does handle deletion or creation, so routing is implied rather than explicit.

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