atera

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

Annotations mark the tool as destructiveHint=true, but the description adds meaningful behavioral context by explaining that a technician comment can be private (is_internal=true) or visible to the end user (false), and that comments can be posted as an end-user contact. It does not state permission requirements or rate limits, but the visibility semantics are an important disclosure.

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

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

The description is two tightly written sentences, front-loading the core action and then parenthetically explaining the modes. The endpoint URL is a useful developer detail without 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 mutation tool with no output schema, the description covers the required parameters and the two posting modes well. It does not describe return values or error behavior, which is a minor gap given the tool's straightforward add-comment nature.

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 baseline is 3, but the description adds value by clarifying the relationship between technician_id, enduser_id, and is_internal—specifying mutually exclusive posting modes and the effect of is_internal. It does not cover the other parameters (e.g., timestamp_utc, technician_email), but those are already documented 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?

The description states a specific verb and resource ('Add a comment to a ticket') and clearly distinguishes the two posting modes (technician vs. end user). An agent can identify the tool's exact function 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?

It explains that a comment can be posted either as a technician (using technician_id) or on behalf of an end user (using enduser_id), and clarifies the meaning of is_internal for private notes versus visible replies. However, it does not name alternative tools (e.g., list_ticket_comments for reading) or state when not to use this 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 supply only destructiveHint=true, so the description must carry the rest of the behavioral burden and does not: it is silent on duplicate-email handling, idempotency, whether the write is reversible, what permissions/auth are needed, and what the call returns. The endpoint string adds implementation trivia rather than behavioral context for the caller. (Note: 'create' vs destructiveHint=true is a mild tension but is a common conservative marking for POST writes, so it is not treated as a contradiction.)

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

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

Two short clauses with the action and its core constraint front-loaded; nothing is padded or restated from the title. The trailing API endpoint reference is the only low-value token, but it is brief.

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 mutation tool with no output schema and minimal annotations, the description leaves real gaps: it never states what the response contains (e.g. the new contact's identifier) even though no output schema exists to cover that, and it omits duplicate/error behavior. An agent can call it, but not confidently predict the outcome.

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

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

Schema description coverage is only 44% across 9 parameters, so the description should compensate more than it does. It does clarify the customer_id/customer_name alternative and that a customer association is expected, but the remaining fields (phone, mobile_phone, job_title, first_name, last_name, is_contact_person) receive no added meaning beyond the bare schema properties.

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 the scoping constraint ('under an existing customer'), which is enough to separate it from list/read siblings. It does not, however, name or differentiate itself from any sibling explicitly (e.g. atera_list_contacts, atera_create_ticket), so it stops short of a 5.

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

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

The parenthetical 'give customer_id or customer_name' is genuinely useful invocation guidance for the association requirement, but there is no when-to-use/when-not-to-use guidance, no statement of prerequisites (e.g. an existing customer must already exist), and no routing to alternatives. Usage is implied rather than framed.

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?

With only destructiveHint=true in annotations, the description adds genuine behavioral value by disclosing a side effect: supplying the name/email triple silently creates a new contact. It also names the underlying endpoint (POST /api/v3/tickets). It stops short of covering notifications, permissions, or idempotency, but the contact-creation disclosure is meaningful.

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

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

Three tight sentences with the core action front-loaded, followed by the contact-identification rule and a terse endpoint reference. No filler, every sentence earns its place.

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

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

For a 13-parameter create tool with no output schema, the description covers the essential action, the trickiest parameter interaction, and the endpoint. It omits any mention of what is returned (e.g., a new ticket ID), which would help an agent chain calls, 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 77% (already high), so baseline is 3, but the description adds a business rule the schema cannot express: end_user_id is mutually exclusive with the end_user_first_name/last_name/email trio. That exclusivity is not encoded anywhere in the JSON schema and is the key thing an agent must get right.

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 ('Open a new helpdesk ticket'), immediately distinguishing it from siblings like atera_update_ticket and atera_add_ticket_comment. An agent knows exactly what this tool produces 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?

Provides implied usage context (create a ticket) and a routing rule for identifying the end user, but never compares against alternatives such as atera_update_ticket or atera_add_ticket_comment, nor states any when-not-to-use condition. The 'either/or' rule reads more as a parameter constraint than situational 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 readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST call (GET /api/v3/agents/machine/{machineName}), which is consistent but adds little behaviorally; it says nothing about pagination/return 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, front-loaded with the purpose and followed by an example and endpoint reference. No filler and nothing 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 simple read-only lookup with annotations covering safety and a fully documented schema, the description is largely sufficient. It could mention pagination/when multiple agents match, but no output schema exists and the core need is met.

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 parameters (page, machine_name, items_in_page) are fully documented in the schema. The description adds value by giving a concrete machine-name example format ('DESKTOP-4F2K9'), which clarifies what kind of value is expected.

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+resource ('Find the agent(s) installed on a machine') and a concrete example machine name, making the lookup key explicit. It does not name any sibling tool (e.g. atera_get_agent, atera_list_agents) to differentiate itself, so it stays at 4 rather than 5.

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

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

There is no when-to-use guidance, no comparison to alternatives like atera_get_agent (by ID) or atera_list_agents (all agents), and no statement of prerequisites. The intended scenario is only weakly implied by the phrase 'by its machine name'.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does: the underlying endpoint (GET /api/v3/account) and the cost/cheapness hint that this is a lightweight validation call, which helps an agent decide to use it as a probe. It doesn't discuss auth failure behavior or rate limits in detail.

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: the payload is front-loaded first, the practical use case second, with the endpoint appended as reference. 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?

There is no output schema, so the description carries the return-value burden and discharges it by naming the fields returned (company name, plan, country, timezone). For a no-parameter read tool this is fully sufficient to invoke correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4.

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 tied to this key), and enumerates the returned fields (company name, plan, country, timezone). No sibling tool covers the account resource, so the agent can distinguish it immediately from the ticket/agent/customer 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?

Gives a clear use case — 'A cheap way to confirm the key works' — which tells the agent when this tool is worth calling. It stops short of stating when not to use it or naming an alternative, so it falls just short of a 5.

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

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

Annotations declare readOnlyHint=true, and the description usefully enumerates the response payload (device inventory, online status, IPs, OS build, last reboot), which matters because no output schema exists. It stops short of noting error behavior for an unknown AgentID or any auth/permission requirements, so it is helpful but not complete.

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

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

One tight sentence carrying the action, key, and return contents, plus a compact endpoint citation. Nothing is padded and the most important information 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-only single-entity fetch with a fully documented parameter and annotations covering safety, the description supplies what the structured fields cannot: the shape of the returned data. Only minor gaps remain (unknown-ID behavior, permissions), so it is nearly complete for this tool's complexity.

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

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

The single parameter is fully documented in the schema (100% coverage), including its integer type and bounds. The description's 'by its AgentID' merely restates the parameter's meaning rather than adding format or lookup guidance, 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 ('Fetch') and resource ('a single agent'), scoped by 'AgentID'. The word 'single' implicitly distinguishes it from the sibling atera_list_agents, and it enumerates the returned fields (inventory, online status, IPs, OS build, last reboot), leaving no ambiguity about what the call resolves to.

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 its AgentID' implies the tool is used when a specific agent identifier is already known, which is the right context. However, it never states when to reach for this over atera_list_agents or atera_find_agents_by_machine, nor any preconditions, so usage is only implied.

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

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

readOnlyHint=true already declares this is a safe read, so the annotation carries the safety profile. The description adds valuable context that the key must be a DeviceGuid, not the AgentID, and maps to the two Atera API endpoints. It does not describe return format or pagination, so beyond annotations it adds moderate but not rich behavioral detail.

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 plus an API reference, all front-loaded. Every clause earns its place: scope, mode distinction, identifier sourcing, and endpoint mapping.

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

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

For a two-parameter read tool with full schema coverage and no output schema, the description covers the important correctness risk (which ID to pass) well. It could note the return shape or that 'kind' defaults to available, but nothing critical for correct invocation 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%, so the baseline is 3, but the description adds a genuinely useful semantic clarification: the identifier is the device's DeviceGuid, explicitly not the AgentID, which prevents a common wrong-parameter error. The available/installed meaning is echoed but is already covered by the enum description.

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

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

The description states a specific verb (list) and resource (Windows/OS patches) scoped to one device, and explicitly distinguishes the two modes (AVAILABLE vs INSTALLED). An agent can tell this apart from siblings like atera_get_agent 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?

It gives clear context: use this on a single device identified by DeviceGuid, and it names where that ID comes from (atera_list_agents / atera_get_agent). It stops short of stating when NOT to use it versus alternatives, but the usage path is unambiguous.

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 the underlying REST endpoint and a summary of returned fields, but says nothing about auth requirements, error behavior when the id is unknown, or rate limits.

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

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

One sentence plus an endpoint reference, front-loaded with the action and resource before the field list. Nothing is redundant or padded.

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

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

There is no output schema, and the description partially compensates by naming address, domain, phone, and notes as the payload. For a simple one-parameter getter this is nearly sufficient; a fuller field list or an error-case note would 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 single parameter is documented in-schema as the CustomerID with a positivity constraint, so the description carries little extra burden. 'By id' reinforces the schema but adds no format or sourcing detail beyond it.

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 ('Fetch a single customer by id') and enumerates the returned fields, so the intent is unambiguous. It does not name the sibling atera_list_customers, relying on 'a single customer' to imply 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?

Usage is only implied: 'by id' signals that the agent needs a customer_id in hand, but the description never says when to prefer this over atera_list_customers or a search tool, nor 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?

The readOnlyHint annotation already establishes this is a safe, non-mutating read, so the description carries a lighter burden. It adds the underlying REST endpoint for cross-reference, but says nothing about what happens on an invalid/missing TicketID or what the payload contains.

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

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

Two short sentences, front-loaded with the action and resource. The trailing REST endpoint reference is slightly redundant for an agent but is compact and harmless, so the description wastes 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 simple single-record read with two fully documented parameters, no output schema, and a readOnlyHint, the description provides enough to call it correctly. It could be marginally richer with error/not-found behavior, but nothing essential 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% (ticket_id and include_relations are both documented in the schema), so the baseline is 3. The description only echoes 'TicketID' and adds no format, constraint, or semantics for the optional include_relations flag.

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 ('Fetch a single ticket by its TicketID'), so an agent knows exactly what the tool returns. It doesn't explicitly contrast itself with siblings like atera_list_tickets or atera_update_ticket, but the singular-scope wording makes the distinction reasonably evident.

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: fetch this when you already have a TicketID. There is no guidance on when to prefer it over atera_list_tickets, no mention of prerequisites, and no exclusion criteria, so the agent must infer the selection conditions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond that: the kinds of alerts surfaced and the fields each record carries (severity, device, customer, linked ticket), which matters because there is 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?

Front-loaded with the core verb+resource and kept to essentially one sentence plus an endpoint reference; no filler. The parenthetical field listing is slightly clipped but does not harm readability.

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 3-parameter read-only list tool with full schema coverage, the description covers purpose, returned fields, filtering and the underlying endpoint. It omits pagination behavior and permission requirements, but those are 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%, so page, items_in_page and alert_status are already documented with defaults, ranges and an enum. The description only echoes the status filter and adds no syntax or format detail, 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 ('monitoring alerts'), plus enumerates the alert domains (disk, CPU, availability, hardware) and returned fields. An agent can immediately distinguish this read operation from the sibling atera_resolve_alert mutation.

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?

'Filter by status' implies the tool's usage context, but there is no explicit when-to-use/when-not guidance and no mention of the alternative atera_resolve_alert for acting on an alert. Usage is inferable from the name but not spelled out.

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 corroborates with the API verb (GET /api/v3/contacts), which adds modest confirmation of the read-only nature. It does not disclose pagination behavior, result limits, or what happens with no filters, so it adds little 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?

Two short sentences with the core purpose front-loaded and the API mapping appended compactly. 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 simple list tool with fully documented parameters and no output schema, the description covers the essential purpose and filter scope adequately. Only minor gaps remain, such as whether unpaginated calls return everything or whether filtering is server-side.

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 email, phone, page, and items_in_page are all documented in the schema. The description's mention of whole/partial email and phone matching restates that schema text rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (end-user contacts), and the email/phone search qualifier narrows the scope further. It is clearly distinct from the sibling atera_create_contact, though it does not explicitly differentiate itself from other list tools such as atera_list_customers.

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

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

"Optionally searching by whole or partial email or phone number" implies when the filter parameters are useful, which is decent contextual guidance. However, there is no explicit when-to-use vs. alternative framing 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, so safety is covered. The description adds real value beyond that by disclosing the underlying endpoints (GET /api/v3/contracts vs /contracts/customer/{customerId}), which explains the two operational modes. It does not discuss pagination behavior, though the schema covers page/items_in_page.

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, then the filtering rule, then endpoint detail. Every sentence carries information; nothing is padded.

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

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

For a read-only list tool, the description covers the resource, the returned attributes, and the filter mode. With no output schema, mentioning rates and billing periods is helpful; only pagination behavior is unaddressed, which is a minor gap given the schema fields.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only restates the customer_id behavior ('Only this customer's contracts' vs 'Pass customer_id for one customer's contracts'), adding no syntax or format detail beyond the schema baseline.

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

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

States a specific verb (List) and resource (service contracts), and enumerates the contract types (retainer, block hours, hourly, remote monitoring) plus what fields are returned (rates, billing periods). No sibling tool covers contracts, so an agent can immediately distinguish it from the ticket/customer/agent 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?

Explicitly tells the agent when to pass customer_id ('Pass customer_id for one customer's contracts'), clarifying the single-customer vs all-customers modes. It stops short of naming when NOT to use this tool or naming alternatives, but the usage condition is clear.

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 that the result is paginated and names the backing endpoint, but does not disclose rate limits, authentication needs, or return format details beyond pagination.

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 front-loaded sentence plus a compact endpoint reference. Every element earns its place; no repetition or 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 simple read-only list tool with two fully documented optional parameters and safety annotations, the description covers the essential purpose and pagination behavior. It omits filtering/sorting context, but nothing critical for correct invocation 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%, so both page and items_in_page are fully documented in the schema. The description only says 'paginated' and does not add parameter-specific meaning, 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?

States a specific verb and resource ('List the customers/client companies') and notes pagination, which clearly distinguishes it from singular read tools like atera_get_customer. It does not explicitly call out how it differs from the sibling 'list' tools, keeping it 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 verb and resource: an agent should call it when it needs a paginated list of customers. However, no explicit when-to-use guidance, prerequisites, or alternatives to atera_get_customer are provided.

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, covering the safety profile. The description adds value by disclosing the underlying API endpoint (GET /api/v3/knowledgebases), but says nothing about pagination behavior, default ordering, or whether ratings/fields can be absent.

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. The trailing endpoint reference is mildly useful metadata but not essential for invocation, so it is not a perfect 5.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage, the definition is nearly sufficient; naming the returned fields partially compensates for the missing output schema. Only pagination/return-shape behavior is absent.

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

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

Schema description coverage is 100% — both 'page' and 'items_in_page' carry 1-based/default and range documentation. The description adds no parameter-level meaning, 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?

States a specific verb ('List') and resource ('knowledge-base articles') and enumerates the returned fields (product, keywords, section, category, ratings). The resource is distinct from all siblings, though it does not explicitly contrast itself with other list_* tools like atera_list_tickets.

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, when-not-to-use, or alternative tooling is given. The agent must infer that this is the tool for browsing KB content purely from the noun in the name; nothing in the description routes it against the 19 sibling tools.

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, non-mutating read. The description adds genuinely useful context beyond the annotation — that the payload contains both end-user and technician replies with internal notes flagged — but says nothing about pagination behavior, ordering, or volume, despite the schema exposing page and items_in_page.

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 tightly written sentence front-loads what the tool returns, and the trailing endpoint reference is compact and useful for API mapping. There is no filler or redundant 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 read-only list tool with a fully documented schema, an existing readOnlyHint, and no output schema, the description covers scope and returned content adequately. Minor gaps remain around pagination and result ordering, but nothing essential to correct invocation 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%, so ticket_id, page, and items_in_page are fully documented in the schema itself. The description only echoes the ticket scope via the endpoint path and adds no format or usage nuance beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List the comment thread on one ticket') and clarifies the content returned — end-user and technician replies with internal notes flagged. This clearly separates it from atera_add_ticket_comment and atera_get_ticket, so an agent can identify it 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?

Usage is implied: read the comment thread for a given ticket. However, there is no explicit when-to-use guidance, no mention of when to prefer atera_get_ticket or atera_list_tickets instead, and no prerequisites (e.g., needing a valid TicketID) stated. Implied-only usage lands at 3.

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 this as a safe read, so the description's incremental burden is lower. It adds useful context by disclosing the returned fields and the backing endpoint (GET /api/v3/tickets). It does not describe pagination behavior or how the SLA-duration/

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 is returned and how to filter; no filler. The trailing endpoint reference is marginally useful for API tracing but is the closest thing to overhead.

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

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

With no output schema, the description usefully compensates by enumerating the fields returned, and annotations cover the safety profile. For a read-only list tool with fully documented parameters, this is essentially complete; only pagination semantics remain implicit via the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including defaults and ranges — baseline is 3. The description mentions customer and status filtering (mapping to customer_id and ticket_status) but adds nothing about page, items_in_page, or include_relations.

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 ("List") with a specific resource ("helpdesk tickets") and enumerates the returned fields (priority, status, type, end user, technician, SLA durations, last comments). This clearly separates it from atera_get_ticket and atera_list_ticket_comments. It stops short of naming 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?

"Filter by customer and/or status" gives an implied usage cue for narrowing results, 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 only loosely implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing the record composition (technician, start/end, billable, on-site, rate) and mapping to the underlying Atera endpoint, which meaningfully characterizes the output; it does not, however, mention pagination 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 tight sentences: the scope and subject come first, the field enumeration second, and the endpoint reference last. Zero filler, every clause carries information.

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

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

With no output schema, the description usefully enumerates what each record contains, and the readOnlyHint covers safety. Minor gap: pagination behavior and total-count semantics are left to the schema, but nothing essential for correct invocation 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%, so page, ticket_id, and items_in_page are already fully documented with defaults and ranges. The description 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 (time entries / work hours on one ticket), and enumerates the returned fields (technician, start/end, billable, on-site, rate). This clearly distinguishes it from siblings like atera_get_ticket and atera_list_ticket_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 scope ('on one ticket') implies when to use it, but there is no explicit when-to-use guidance, no mention of alternatives (e.g. use atera_get_ticket for ticket metadata), and no prerequisites such as required permissions. Usage is only inferable.

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. The description adds genuinely useful behavior: resolving does not suppress the alert permanently — if the underlying condition persists, Atera re-raises it on the next check. It also discloses the backing endpoint. It stops short of stating auth requirements or whether the resolve is idempotent/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 that are front-loaded with the core action, followed by the key behavioral caveat. No padding; 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?

For a one-parameter tool with no output schema and annotations covering the destructive flag, the description supplies the essential effect and the re-raise caveat. It omits how to find an alert ID and permission requirements, but nothing critical to correct invocation 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?

Single required parameter with 100% schema description coverage, so the schema already defines alert_id (AlertID, positive integer). The description adds no format, sourcing, or constraint detail beyond the schema. Baseline 3 is appropriate when structured data carries the parameter definition.

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

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

States a specific verb + resource ("Mark one monitoring alert as resolved") and the effect is unambiguous. An agent can immediately distinguish this mutating tool from the read-oriented sibling atera_list_alerts. No tautology or ambiguity.

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

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

The description implies usage (resolve an alert you no longer want active) and explains the consequence of resolving, but gives no explicit when-to-use routing, no mention of how to obtain an alert_id (e.g., via atera_list_alerts), and no prerequisites. 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 declare destructiveHint=true, so the safety profile is partly covered. The description adds a genuinely useful behavioral fact beyond the annotations — that unpassed fields are left untouched (PATCH-like semantics on a PUT) — but it says nothing about irreversibility, required permissions, or status-transition effects for a mutation 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 padding, and the field list is front-loaded before the partial-update constraint and the endpoint reference. Every clause carries information.

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

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

For a mutation tool with no output schema and only a destructiveHint annotation, the definition covers the operative facts: what can be changed, that omitted fields stay put, and the underlying endpoint. It is close to complete, missing only error/permission behavior.

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 moderate (63%) with enums already documenting type/impact/priority. The description names most mutable fields, mapping onto the parameters, but adds no syntax, format, or selection guidance for the two technician reassignment parameters (email vs contact_id) that the schema does not fully disambiguate.

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+resource ('Change a ticket') and enumerates the mutable fields (title, status, type, priority, impact, assigned technician), so an agent can tell it apart from atera_get_ticket and atera_create_ticket. It stops short of explicitly naming those siblings, which keeps it from 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 rather than stated: modifying an existing ticket is the obvious context, and 'Only the fields you pass are sent' usefully signals partial-update semantics. There is no explicit when-to-use routing against alternatives or any prerequisite/permission guidance.

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