Atera MCP by usefulapi

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

Annotations supply only destructiveHint=true, so the description carries most of the behavioral burden and does so usefully: it discloses that is_internal=false produces a reply the end user sees, a real side effect an agent must reason about. It says nothing about permission requirements, whether a technician and end-user identity can be combined, or rate limits, so it is not fully transparent.

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

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

Two sentences, no padding. The core action leads, and the mode split plus is_internal semantics follow immediately, with the endpoint tacked on as a cheap identifier.

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 tool with no output schema, the description covers purpose, the authoring-mode fork, and the visibility flag, which is what an agent needs to call it correctly. Edge cases such as supplying both technician_id and enduser_id, or error behavior, remain 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 already 100%, so the baseline is 3, but the description adds meaning the schema does not: it frames technician_id and enduser_id as mutually exclusive authoring modes rather than independent optional fields. It does not clarify the interaction between timestamp_utc and technician_email beyond what their own descriptions carry.

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

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

States a specific verb (add) and resource (comment on a ticket) and even names the backing endpoint, POST /api/v3/tickets/{ticketId}/comments. It is immediately distinguishable from the sibling atera_list_ticket_comments, which reads rather than writes comments.

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

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

The description gives concrete routing guidance for the two authoring modes: as a technician via technician_id, or on behalf of an end user via enduser_id, with is_internal controlling visibility. It stops short of any explicit when-not-to-use or alternative-tool statement (e.g., when to prefer atera_update_ticket instead).

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 destructiveHint annotation already signals a write operation and the description is consistent with it, adding the parent-existence prerequisite. However, it says nothing about permissions/authentication, duplicate-email handling, or what happens to fields not supplied — meaningful gaps for a mutation tool whose only annotation is destructiveHint.

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 operation and its key decision (which parent identifier to pass) front-loaded. The trailing 'Atera: POST /api/v3/contacts' is low-value endpoint trivia but costs little.

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

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

For a 9-parameter create tool with no output schema, the description covers the essential decision (parent linkage) and the operation, but leaves the agent without guidance on the field-heavy area and on failure modes.

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 44%, and five parameters (phone, job_title, first_name, last_name, mobile_phone) are undocumented in both places. The description usefully resolves the customer_id-vs-customer_name choice, but adds little else beyond what the schema's own descriptions already say.

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

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

States a specific verb and resource ('Create a new end-user contact') plus its scoping constraint ('under an existing customer'), which cleanly separates it from the read-oriented sibling atera_list_contacts. An agent can identify the operation without opening the schema.

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

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

Gives a clear prerequisite and the two acceptable ways to satisfy it ('give customer_id or customer_name'). It stops short of stating when not to use it (e.g., create the customer first, or use an update tool if the contact already exists).

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden. It does disclose a non-obvious side effect: supplying the name/email trio creates a new contact as part of the call. It does not describe what is returned (no ticket ID), notification behaviour, or defaults applied to unset fields. The destructiveHint=true annotation sits oddly next to a pure create operation, but the description does not directly contradict it.

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, zero padding, and the primary action is front-loaded before the contact-selection rule. The trailing endpoint reference is short and adds traceability rather than bloat.

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 13-parameter mutation tool with no output schema the description covers the main decision point (existing vs new contact), which is the highest-risk ambiguity. It stops short of stating defaults for type/priority/status or the shape of the response, but nothing critical to invoking the tool 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 77%, so baseline is 3, and the description adds a genuine cross-field constraint that the JSON schema cannot express: end_user_id XOR (end_user_first_name + end_user_last_name + end_user_email). That mutually exclusive branching is exactly the kind of semantics an agent needs before filling the 13 parameters.

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?

"Open a new helpdesk ticket" names a specific verb and resource, and the endpoint reference (POST /api/v3/tickets) confirms the operation. It is clearly distinguishable from atera_get_ticket, atera_update_ticket and atera_add_ticket_comment, though the description 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?

The description gives a real conditional rule for the contact branch (use end_user_id for an existing contact, or the three name/email fields to create a new one). However, it offers no guidance on when to use this tool versus sibling operations such as atera_update_ticket or atera_add_ticket_comment, and no prerequisites or permissions 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?

The readOnlyHint annotation already establishes this as a safe read. The description adds the underlying GET endpoint and an example machine-name format, confirming read semantics, but says nothing about return shape, pagination, or empty/multiple matches beyond the vague 'agent(s)'.

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

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

Two short sentences, zero filler. The purpose and lookup key are front-loaded, and the API endpoint is a compact, useful trailing detail.

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

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

For a parameterized read lookup with full schema coverage and no output schema, the description covers what the tool does, the key format, and the endpoint. Only the behavior of pagination and multiple matches is left implicit, which is minor for this tool type.

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 machine_name, page, and items_in_page are already documented. The description only adds an example machine name (DESKTOP-4F2K9), which reinforces format but does not add meaning beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (Find), resource (agent(s) installed on a machine), and lookup key (machine name), with a concrete example value. It is distinguishable from siblings like atera_get_agent and atera_list_agents, though it never names them explicitly.

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

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

Usage is implied by the lookup key: use this when you know a machine name rather than an agent ID. However, there is no explicit when-to-use guidance and no mention of the alternative tools (atera_get_agent for agent IDs, atera_list_agents for enumeration).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context beyond that: the raw endpoint (GET /api/v3/account), the cost/latency hint ("cheap"), and the fact that the result is scoped to the caller's own key. It does not mention rate limits or auth scope detail, which are minor for a zero-argument 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 sentences plus an endpoint reference; the scope and returned fields are front-loaded and every clause carries information. No padding 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?

With no output schema available, the description compensates by listing the payload contents (company name, plan, country, timezone). Combined with the safety annotation and zero-parameter schema, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly adds no spurious argument discussion.

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

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

States a specific verb (Fetch) and resource (the Atera account this key belongs to), and even enumerates the fields returned: company name, plan, country and timezone. An agent can distinguish it from atera_get_customer or atera_get_agent because the scope is explicitly tied to the API key's own account.

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?

"A cheap way to confirm the key works" gives a concrete when-to-use scenario (credential validation). It stops short of naming alternatives or stating when *not* to use it (e.g. versus atera_get_customer for customer-level detail), so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description usefully previews what the payload contains (inventory, online status, IPs, OS build, last reboot) and cites the backing endpoint, but says nothing about auth requirements, pagination, or error behavior on an invalid ID.

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

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

A single sentence with the resource and scope front-loaded, followed by the endpoint reference. No filler, and every clause (identifier, returned fields, API path) carries information.

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

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

For a single-resource read with one documented parameter and no output schema, the description supplies the missing return-value preview along with the identifier contract and endpoint. An agent has everything needed to invoke it correctly.

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

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

One required integer parameter with 100% schema description coverage, so the schema already documents agent_id fully. The description's 'by its AgentID' restates the parameter without adding format, range, or lookup-hint value, 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?

States a specific verb and resource with clear scope — 'Fetch a single agent by its AgentID' — and enumerates the returned fields. The 'single' framing plus the field list implicitly separates it from atera_list_agents and atera_get_agent_patches, but no sibling is ever named explicitly, so the differentiation is left to inference.

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: call this when you have an AgentID and need that one device's details. There is no explicit statement of when to prefer it over atera_list_agents or atera_find_agents_by_machine, and no prerequisites or exclusions are given.

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

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

readOnlyHint=true already covers the safety profile, so the description's added value is the two-mode behavior (available vs installed) and the concrete API endpoints being wrapped. It omits return volume, pagination, and rate-limit behavior, but adds meaningful context beyond the annotations.

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

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

The scoping statement is front-loaded in the first clause, and each sentence adds non-redundant information (modes, parameter source, endpoints). No filler.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers purpose, both modes, parameter provenance, and the wrapped endpoints. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above it by clarifying that device_guid is a DeviceGuid sourced from sibling tools and explicitly ruling out AgentID. The kind enum's meaning is already in the schema, so no extra credit there.

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 (Windows/OS patches), scoped to one device, and splits the result space into AVAILABLE vs INSTALLED. An agent can distinguish it from siblings like atera_get_agent or atera_list_agents without opening any schema.

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

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

Explicitly tells the agent where device_guid comes from (atera_list_agents / atera_get_agent) and that AgentID is NOT accepted, which is the key selection pitfall. It does not, however, state when to prefer this over any alternative patch source or list any exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the underlying REST call (GET /api/v3/customers/{customerId}) and the shape of the returned fields, which is useful, but says nothing about error behavior for a missing/nonexistent id.

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

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

Two short sentences, front-loaded with the action and then the endpoint reference. No filler, though the endpoint line is mildly redundant for a pure agent caller.

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

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

For a simple single-entity read with annotations covering the safety profile, the description enumerates the return fields and the underlying endpoint. No output schema is present, but the field list largely compensates, so an agent has enough to call it correctly.

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

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

Schema coverage is 100% for the single customer_id parameter, so the schema already documents it. The description adds nothing beyond 'by id' — no format or validity notes. Baseline 3 is correct when the schema carries the parameter semantics.

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

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

States a specific verb 'Fetch' plus resource 'a single customer' and names the returned fields (address, domain, phone, notes). The 'single customer by id' phrasing distinguishes it from the listing sibling, though it never names atera_list_customers explicitly.

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

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

Usage is implied by 'by id' — a lookup when the CustomerID is known — but there is no explicit when-to-use guidance or routing to atera_list_customers for enumerating customers. An agent must infer the boundary between this and the list tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered and the description adds no behavioral context such as auth requirements, error behavior for unknown IDs, or rate limits. The only extra content is the underlying REST path, which is infrastructure detail rather than agent-facing behavior.

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

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

Two short sentences with the key lookup semantics front-loaded and zero filler. Nothing could be removed without losing information.

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

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

There is no output schema, so the description carries some burden for describing what comes back, and it says nothing about the returned ticket shape, the effect of include_relations, or behavior on a nonexistent ID. Adequate for a simple single-record read, but with clear gaps.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema; baseline 3 applies. The description names TicketID but ignores include_relations entirely, adding nothing 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 ('Fetch'), resource ('a single ticket'), and lookup key ('by its TicketID'), which separates it from the bulk-oriented atera_list_tickets and the mutating atera_update_ticket. It stops short of explicitly naming those siblings, so an agent must infer the distinction.

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-to-use guidance is given. The description never states that atera_list_tickets should be used for browsing/searching and this tool only when a TicketID is already known, nor does it mention any 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 only declare readOnlyHint=true; the description carries the rest and adds real value by enumerating the data each agent record returns (online status, last seen, OS, hardware, logged-in user) and mapping to the two concrete REST endpoints. It still omits rate limits, result-size/pagination behaviour and whether hardware detail is expensive to fetch.

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 what the tool returns before the optional filter and the underlying endpoint. Every sentence carries information; nothing is padded or repeated from 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 read-only list tool with no output schema, the description covers the returned fields, the optional customer scoping and the API route, which is enough for an agent to call it correctly. It stops short of describing result-set size or how to page through a large estate, which matters given a 900-tenant installation.

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

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

Schema description coverage is 100%, so page, items_in_page and customer_id are already documented with bounds and defaults. The description's 'Pass customer_id to list only one customer's devices' merely restates the schema's 'Only this customer's agents,' adding no new syntax or semantics — 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 precise verb (List) with the resource (Atera agents) and even defines the domain term — 'the managed machines' — then enumerates the returned attributes. It clearly reads as the bulk-listing tool, but it never names the neighbouring single-agent tools (atera_get_agent, atera_find_agents_by_machine), so differentiation is inferred rather than stated.

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

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

'Pass customer_id to list only one customer's devices' gives parameter-level usage, not tool-selection guidance. There is no statement of when to prefer this over atera_find_agents_by_machine or atera_get_agent, and no guidance on pagination strategy for large tenants.

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

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

Annotations declare readOnlyHint=true, so safety is covered; the description adds that results carry linked tickets and enumerates alert categories, which is meaningful context beyond the annotation. It discloses the underlying API endpoint, adding traceability. It does not mention pagination or result limits, which would be useful for a list operation.

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 plus an endpoint reference, all front-loaded with the resource and scope before the filter detail. No filler, though the endpoint notation is marginally redundant for an agent.

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, three-parameter list tool with full schema coverage and no output schema, the description is nearly complete: it names the resource, the returned fields, and the status filter. A brief note on pagination defaults would close the 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 100%, so page, items_in_page, and the alert_status enum are fully documented in the schema. The description's 'Filter by status' merely restates the alert_status parameter without adding syntax or format detail, so baseline 3 applies.

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

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

Specific verb (List) plus resource (monitoring alerts), and it enumerates the alert categories and the linked fields returned (severity, device, customer, ticket). This clearly distinguishes it from sibling list tools like atera_list_tickets or atera_list_agents.

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

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

States 'Filter by status' which signals the main filtering use case, but gives no explicit when-to-use guidance, no mention of pagination behavior, and no routing to alternatives such as atera_resolve_alert for acting on alerts. Usage is implied rather than guided.

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 endpoint and the whole/partial matching behavior of the filters, but says nothing about pagination behavior, result ordering, or total counts — meaningful gaps for a list tool with no output schema.

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

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

Two short sentences, front-loaded with the core action and filters, ending with the endpoint reference. 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?

For a read-only paginated list tool with full schema coverage and annotations carrying safety, the description covers purpose and filtering adequately. The absence of any note on pagination limits or result shape is a minor gap given there is no output schema.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, and the description largely restates the email/phone matching semantics it provides. Baseline 3 applies; it adds no syntax, format, or matching-rule 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 (list) and resource (end-user contacts) plus the filter capability, and includes the underlying API endpoint. It is clearly distinguishable from the write-oriented siblings like atera_create_contact, though it does not explicitly name 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?

The word 'optionally' implies the filters are not required and gives context for when search is used, but there is no explicit when-to-use/when-not guidance or reference to alternative tools. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this by naming the two GET endpoints used. However, it adds nothing about pagination behavior or result size limits, so beyond confirming the read-only nature it does not deepen the behavioral 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?

Three compact sentences that front-load the purpose before the filtering hint and the underlying endpoints. The endpoint mapping is arguably extra, but it is short and does not dilute the core statement.

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

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

For a read-only, three-optional-parameter list tool with no output schema, the description covers what the resource is, what fields it returns, and how to filter. It leaves pagination semantics to the schema, which is reasonable given full schema coverage.

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

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

Schema description coverage is 100%, so page, customer_id, and items_in_page are fully documented in the schema already. The description's 'Pass customer_id for one customer's contracts' duplicates the schema text, adding no semantics beyond the baseline.

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

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

States a specific verb ('List') and resource ('service contracts'), then enumerates the contract types (retainer, block hours, hourly, remote monitoring) and the data returned (rates, billing periods). No sibling tool covers contracts, so this is unambiguously distinct.

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?

Explicitly tells the agent that passing customer_id scopes the result to one customer's contracts, which is the key usage decision for this tool. It stops short of stating when-not to use it or naming alternatives, but nothing else in the sibling set overlaps.

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 only needs to add context — it contributes the pagination behavior and the underlying endpoint (GET /api/v3/customers). It says nothing about rate limits, result ordering, total-count metadata, or error behavior, so the added value is modest.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the endpoint reference trailing as secondary context. Nothing redundant or misplaced.

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

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

There is no output schema, so the description would ideally indicate what a customer record contains or that pagination metadata is returned; it does neither. For a simple read-only list with full parameter coverage this is still workable, but the return-shape gap keeps it at minimum-viable.

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%: both 'page' and 'items_in_page' are documented with types, bounds and defaults. The description only restates that results are paginated, adding no format or interaction 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 and resource — 'List the customers (client companies) managed in Atera' — and even adds the domain noun disambiguation '(client companies)' plus 'paginated'. It does not explicitly name the sibling it contrasts with (atera_get_customer for a single customer), so it stops short of a 5.

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

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

Usage is only implied: the word 'paginated' hints at bulk enumeration, but there is no explicit when-to-use vs when-not, no pointer to atera_get_customer for single-record retrieval, and no guidance on looping pages. Adequate but leaves selection 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 the safety profile is covered by structured data. The description adds value by naming the returned fields and the underlying Atera endpoint, but says nothing about pagination behavior or result ordering 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 sentences, zero waste, with the field inventory front-loaded and the endpoint reference kept short. Nothing could be removed without losing information.

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

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

With no output schema, the description compensates by enumerating the returned fields (product, keywords, section, category, ratings). Pagination is covered by the schema parameters, so the definition is nearly complete for a simple read-only 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 both 'page' and 'items_in_page' are fully documented with defaults and bounds in the schema. The description adds no parameter-level detail, so 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?

Specific verb+resource ('List knowledge-base articles') and it enumerates the returned fields, so the agent knows exactly what the call yields. It does not need sibling differentiation since no other KB tool exists in the sibling list, but it also does not state scope beyond the resource 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 when-to-use guidance, no exclusions, and no mention of alternatives or prerequisites. The listing intent is only implied by the verb 'List'; an agent must infer the context 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?

readOnlyHint=true already establishes the safety profile, and the description usefully adds what the call actually returns — end-user and technician replies with internal notes flagged — which matters because there is no output schema. It stops short of disclosing pagination behavior or default/limits, which the schema covers only via parameter descriptions.

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

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

Two compact clauses: the payload description first, then the backing endpoint. No filler, no restatement of the title, and the most decision-relevant content is front-loaded.

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

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

For a simple read tool with a fully-documented 3-parameter schema and readOnly annotations, the description covers the essentials and compensates for the missing output schema by describing the comment types returned. Pagination behavior for walking long threads is the one unaddressed item.

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 ticket_id, page, and items_in_page are already documented in the schema with defaults and bounds. The description adds no extra syntax, format, or ordering detail 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 (List) and resource (the comment thread on one ticket), and scopes it to a single ticket id. The distinction from the sibling atera_add_ticket_comment and from atera_get_ticket is immediate from the verb+resource pairing.

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: call this when you need the comment history for a known ticket. No explicit when-to-use, when-not-to-use, or named alternative (e.g. atera_get_ticket for the ticket body itself) is provided, so guidance stays at the implied level.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds real value beyond that by enumerating the returned data shape (priority, status, type, end user, technician, SLA durations, last comments) in the absence of an output schema, and cites the underlying endpoint. It does not mention pagination behavior or default page sizing, which keeps it from a 5.

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

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

Three short sentences with zero filler: scope and returned fields first, filtering second, upstream endpoint last. Every clause carries information and nothing is repeated.

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

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

With no output schema, the description compensates by naming the fields returned, and pagination defaults live in the schema. For a read-only list tool with full schema coverage this is close to complete; only pagination/ordering behavior and result-set size expectations are unstated.

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

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

Schema description coverage is 100%, so all five parameters (page, customer_id, items_in_page, ticket_status, include_relations) are already documented with types, bounds, and defaults. The description only echoes the customer/status filtering already covered in the schema and adds nothing about pagination or include_relations. Baseline 3 is correct.

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 helpdesk tickets') plus an enumeration of the fields returned (priority, status, type, SLA durations, last comments). That clearly separates it from siblings like atera_get_ticket, atera_create_ticket and atera_update_ticket. It stops short of naming those siblings explicitly, so it is a clear 4 rather than a 5.

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

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

The sentence 'Filter by customer and/or status' gives implied usage context for the two filtering parameters, but there is no statement of when to prefer this tool over atera_get_ticket or atera_list_ticket_comments, and no exclusions or prerequisites. Usage is inferable but not guided.

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 covers the safety profile, and the description adds real value by disclosing the shape of each returned record (technician, start/end, billable, on-site, rate) plus the underlying Atera endpoint. It does not mention pagination or ordering behavior, though those are visible in the schema.

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

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

One tight sentence plus the raw endpoint reference; the resource and returned fields are front-loaded with zero filler. Every clause earns its place.

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

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

With no output schema, the description usefully names the fields each entry contains, and pagination controls are covered by the schema. Nothing critical is missing, though ordering/limits on the listing are not addressed.

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 (ticket_id, page, items_in_page) are already documented in the schema. The description only reinforces the single-ticket scoping and adds no new parameter 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?

States a specific verb (List) and resource (time entries / work hours on one ticket), and enumerates the fields returned (technician, start/end, billable, on-site, rate). An agent can distinguish this from atera_list_ticket_comments or atera_get_ticket without opening any schema.

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

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

The scope 'one ticket' implies it is used when work-hour detail for a single ticket is needed, but there is no explicit when/when-not guidance and no named alternative among the siblings. 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 carry only destructiveHint=true, so the description adds the genuinely useful behavioral trait that the resolution is not permanent: if the condition persists the alert resurfaces on the next check. That is non-obvious, effect-level context an agent cannot get from the annotations. It does not explain why the operation is flagged destructive or whether the mark is reversible.

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 action and followed by the key behavioral caveat. The trailing 'Atera: PUT /api/v3/alerts/{alertId}' restates what the name and required integer id already convey, which is mild redundancy rather than a real defect.

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 single-parameter tool with no output schema and minimal annotations; the description covers the action, scope, and the important re-raise behavior, which is what an agent needs before invoking it. Only the destructive-flag rationale and any permission requirements are left unstated.

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

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

One parameter at 100% schema description coverage ('The alert's AlertID.'), so the schema already carries the full parameter meaning. The description confirms the target is a single alert but adds no format or source 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?

States a specific verb and resource ('Mark one monitoring alert as resolved') with a clear scope of exactly one alert, which separates it from the read-only atera_list_alerts. It does not name a sibling for contrast, but no sibling overlaps this operation, so the purpose is unambiguous.

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

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

There is no explicit when-to-use statement or named alternative, but there are no competing sibling tools for resolving an alert. The note that Atera re-raises the alert on the next check implies the semantics of resolving (suppression until re-detection), which is implied usage guidance rather than stated 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 supply only destructiveHint=true, so the description carries the rest. It usefully discloses partial-update semantics ('Only the fields you pass are sent') and identifies the endpoint, but says nothing about permission requirements, whether status/priority changes trigger notifications, or whether omitted fields are preserved vs reset beyond the partial-update hint.

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 action and field list front-loaded, followed by the raw endpoint for parity. Nothing is padded, though the endpoint string adds little for an agent that already has 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 an 8-parameter mutation with no output schema and minimal annotations, the description covers the core action and partial-update semantics but omits validation behavior (e.g., invalid/custom status), the reassignment parameter choice, and any side effects of status transitions.

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 a middling 63%, and the description lists the mutable field set, which maps onto the enum/field parameters and adds light clarity. However, it never disambiguates the two reassignment parameters (technician_email vs technician_contact_id) or explains their alternatives/precedence, so it only partially compensates for the coverage gap.

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') and resource ('a ticket') and enumerates the mutable fields, which lets an agent distinguish it from atera_get_ticket, atera_list_tickets and atera_create_ticket without opening a schema. It stops short of naming a sibling explicitly, so it falls just short of a 5.

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

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

Usage is implied by 'Change a ticket's ...' and the PUT endpoint reference, but there is no when-to-use vs when-not guidance and no mention of adjacent tools such as atera_add_ticket_comment or atera_resolve_alert. The patch-semantics note ('Only the fields you pass are sent') is helpful but is behavioral, not routing, guidance.

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