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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description usefully adds matching semantics (substring, case-insensitive) and the optional status filter, which go beyond the annotations. It does not describe result shape or paging behavior in prose, but that is a minor gap.

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 primary search scope front-loaded and the sibling routing placed last. 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 read-only search whose safety profile is fully carried by annotations and whose parameters are 80% documented, the description is sufficient to invoke it correctly. It does not discuss return volume or pagination, but that is not essential here.

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

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

Schema coverage is 80%, so the baseline is 3. The description adds meaning beyond the schema by specifying substring/case-insensitive matching for the query and clarifying that the boolean toggles online-only vs offline-only filtering.

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 (search) and resource (agents) plus the searchable fields, and explicitly distinguishes itself from get_agent_by_machine for exact-name lookups. An agent can select it 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?

Gives explicit routing guidance: 'For an exact machine name prefer get_agent_by_machine', and explains the optional online/offline filter. This names the alternative and the condition that selects it.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the substring-match behavior and the customer scoping option, but says nothing about pagination/scan breadth (up to 500 records by default) or ordering of results, so it adds only modest 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?

Two short sentences with zero filler; the core matching behavior comes first and the motivating use case second. Every clause earns its place.

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

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

With no output schema, the description partly compensates by indicating the useful return artifact (EndUserID), which is more than most search tools offer. It leaves the pagination/limit interaction (limit vs maxPages) to the schema, which is acceptable given full schema coverage, but a note on result shape would make it complete.

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

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

Schema description coverage is 100% – every parameter (limit, query, maxPages, customerId, includeArchived) is documented in the schema itself. The description restates the query semantics and customer restriction but adds no format, syntax, or default information 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 (search) and resource (contacts) plus the matching semantics (name or email contains the query) and an optional scope (one customer). This clearly separates it from list_contacts (enumerate all) and get_contact (fetch one) without the agent needing to open 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?

Gives a concrete when-to-use: 'Use it to get an EndUserID', which tells the agent the downstream goal this tool serves. It does not name an alternative or state when NOT to use it (e.g. when listing all contacts is preferable), so it stops short of full routing 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds matching behavior (substring, case-insensitive, three searched fields), which is genuinely useful, but says nothing about result capping or scanning limits beyond what the schema already encodes.

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 filler, matching semantics front-loaded and the intended outcome (obtaining a CustomerID) trailing. 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 signals the key return value ('get a CustomerID'), and annotations cover safety. It does not explain result shape, ordering or how limit interacts with maxPages scanning, which a search tool returning capped matches would benefit from.

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 itself documents the query string, limit and maxPages defaults carefully. The description's 'contains the query (case-insensitive)' largely restates the query field description, adding case-insensitivity but no format guidance beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 (search customers) plus the exact matching semantics: name, domain or business number, case-insensitive substring. That distinguishes it in spirit from get_customer (ID lookup) and list_customers (unfiltered list), though no sibling is named explicitly, which keeps 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?

The sentence 'Use it to get a CustomerID from a company name' gives one concrete use case, so usage is implied rather than spelled out. It never names alternatives (get_customer, list_customers, find_contacts) or states when this tool is the wrong choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds one genuine behavioral fact – the account is derived from the API key rather than a passed identifier – but discloses nothing about failure modes or whether the key must be valid.

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 twelve-word sentence with zero filler, front-loading the resource identity and immediately following with the returned fields. Nothing could be trimmed without losing content.

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

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

With no parameters and no output schema, the description usefully enumerates the returned fields (company, plan, time zone), which is exactly the missing structured information. It is nearly complete for a trivial read tool; only error behavior on an invalid key is unaddressed.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The mention that the account is implied by the API key correctly signals there is no identifier to supply.

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 phrase 'The Atera account behind the API key' identifies a specific resource and narrows scope to the caller's own account, distinguishing it from sibling lookups like get_customer or get_contact. It is a noun phrase with no explicit verb, relying on the tool name 'get_account' to supply the action, so it is clear but not fully self-contained.

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: 'behind the API key' hints that this is the tool for discovering which account the credentials belong to, versus the customer/contact lookups. There is no explicit when-to-use statement, no alternatives named, and no note that it takes no identifiers.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful detail about the breadth of returned data (hardware, OS, disks, battery, IP/MAC, last reboot), but says nothing about behavior on a missing/invalid agentId or any permission requirements. Modest added value over 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?

A single short clause with no filler, front-loading the returned content. The trailing ellipsis is slightly sloppy and signals the field list is non-exhaustive, but there is no padding to cut.

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 must carry the return-value burden, and it does so at a useful high level by naming concrete field categories. It stops short of stating that it returns a single record keyed by agentId or how it behaves on a nonexistent ID, but for a one-parameter getter this is largely adequate.

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?

With one parameter and 100% schema description coverage, the schema already documents agentId as the required positive integer identifier. The description adds no syntax, format, or constraint information 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 names the resource ('agent record') and enumerates what it contains, so the subject is clear. However, it never states a verb or that it retrieves a single agent by ID, and it offers no differentiation from close siblings like get_agent_by_machine or get_agent_patches. Purpose is inferable but not 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?

There is no guidance on when to use this tool versus list_agents, find_agents, or get_agent_by_machine. The description is a pure content list with no conditions, prerequisites, or alternatives, leaving routing entirely to the agent's inference from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, covering the safety profile. The description adds only the vendor context '(Atera lookup)' — it discloses nothing about result shape, pagination behavior, or the empty-result case.

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 with no filler. It is arguably over-terse — a verb and the return shape could be added without bloat — but nothing is wasted.

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

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

With four parameters, no output schema, and a default summary output, the description should at least hint at what comes back and whether matching is case-sensitive. Annotations and schema cover the safety and paging dimensions, so the gap is real but moderate.

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 75%, so most parameters are documented in the schema itself, including the summary/full and paging options. The description's one contribution is exact-match semantics for machineName, which the schema (plain string, minLength 1) does not state, but it says nothing about full, page, or itemsInPage.

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

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

The description names the resource (agents) and the specific filter (machine name matched exactly), and the 'exactly' qualifier usefully distinguishes it from fuzzy siblings like find_agents. It lacks an explicit verb ('returns') and doesn't name those siblings, 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?

No when-to-use guidance and no alternatives are offered, despite four plausible siblings (list_agents, find_agents, get_agent). Usage is only implied by the exact-match phrase.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the device-scoping and the installed-vs-missing duality, but says nothing about return size, pagination, or freshness of the patch data. With annotations carrying the behavioral load, this is adequate but thin.

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 compact sentence with the resource and lookup key front-loaded and zero filler. It is efficient, though the extreme terseness leaves gaps that other dimensions penalize.

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-only lookup with full schema coverage, rich annotations, and no output schema, a one-line description is nearly sufficient. The remaining gap is minor: nothing is said about result volume or whether the patch list can be large enough to need paging.

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

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

Schema description coverage is 100%: both parameters are documented in the schema, including the installed/available enum, and deviceGuid even points to the sibling get_agent. The description restates 'by DeviceGuid' and 'installed or available' without adding format, casing, or validation 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?

The description names a specific verb ('get'), resource ('Windows updates / patches'), scope ('of a device'), and lookup key ('by DeviceGuid'), and clarifies the two data modes as 'installed or available (missing)'. It is clear what the tool returns, though it never explicitly distinguishes itself from any sibling (there is no other patch tool, so the risk is low).

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. The only implicit guidance is that the 'kind' value selects which set of patches is returned. An agent must infer the use case entirely.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds only content disclosure ('thresholds, message, related ticket'), which is useful but thin; it says nothing about permissions, error behavior if the alertId is unknown, or 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?

One compact fragment with no filler, and the key differentiator (full record vs. list) is front-loaded. The trailing ellipsis, however, leaves the payload description deliberately open-ended rather than crisp.

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 safety, the description is nearly sufficient, but with no output schema it should describe the return shape more concretely than an open-ended '...' list. It also omits the error case for an invalid or missing alertId.

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% for the single alertId parameter (typed integer, exclusiveMinimum 0), so the schema already documents the input. The description adds no syntax, format, or identifier-source detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States the resource (alert) and the scope of the payload (full record with thresholds, message, related ticket), which contrasts implicitly with the sibling list_alerts that returns many. It doesn't explicitly name list_alerts as the alternative, so the 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?

There is no when-to-use guidance and no mention of alternatives such as list_alerts or get_ticket for the related ticket. The phrase 'Full alert record' weakly implies single-record lookup, but the agent must infer that this is the right tool when it already has an alertId.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds nothing beyond that — no note on error behavior for an unknown contactId, no indication of what "full" includes relative to list results.

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 three-word fragment is free of filler, which is appropriate for a trivial single-parameter read, but the brevity is under-specification rather than true conciseness — it omits information rather than compressing it.

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

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

For a simple 1-param read with full annotation coverage and 100% schema coverage, the minimum an agent needs is present. However, with siblings like find_contacts and list_contacts in the same family, the description should have clarified that this requires an existing contactId and returns one record.

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

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

Schema description coverage is 100%, and contactId is documented in the schema as the EndUser ID, so the baseline is 3. The description adds no syntax, format, or lookup-scope detail beyond what the schema already 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?

"Full contact record" contains no verb and effectively restates the title "Get a contact"; the only added nuance is the word "full." It does not distinguish this tool from siblings like find_contacts, list_contacts, or get_customer.

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 mention of prerequisites (e.g. needing a valid contactId), and no reference to the obvious alternatives find_contacts or list_contacts. The agent must infer that this is an ID-based single-record lookup from the schema alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds the payload summary (rates, included hours), which is useful given there is no output schema, but it says nothing about error behavior or whether nested/related entities are hydrated.

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 compact sentence with the payload summary front-loaded and zero filler. It is efficient, though extremely terse for a tool description.

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

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

For a one-parameter read-only getter whose annotations cover the safety profile, the description tells the agent the key contents returned. Only marginal gaps remain (no error/not-found behavior, no distinction from siblings), making it adequate but not rich.

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 contractId parameter has full schema description coverage, so the schema already carries its meaning. The description adds no syntax, format, or lookup-behavior detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific verb+resource ('contract record') and goes beyond the title by stating the notable contents: rates and included hours. It does not explicitly name the sibling list_contracts, though 'Full contract record' implicitly distinguishes it from a list endpoint.

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

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

There is no guidance on when to use this tool versus list_contracts or any other sibling, and no prerequisites or exclusion conditions are given. The agent must infer usage entirely from the tool name and the contractId parameter.

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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds only that the payload is the full record (address, notes, links), which is modest added context; with no output schema, more about return shape or not-found behavior would have helped.

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 short sentence with the key fact ('full customer record') front-loaded and no padding. The trailing ellipsis is informal and slightly undermines precision, but the size is appropriate.

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

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

For a one-parameter read tool with full annotation coverage, this is adequate: the agent knows it is a safe, idempotent full-record fetch. It stops short of describing error/not-found handling or the structure of the returned record, which matters since no output schema exists.

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

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

Schema description coverage is 100% and the single required customerId parameter is documented in the schema, so the baseline is 3. The description adds nothing about the identifier's format or constraints, leaving the schema to do all the work.

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

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

States a specific verb and resource (fetch a single customer) and the parenthetical 'address, notes, links…' signals it returns the complete record rather than a summary. It implicitly separates itself from list_customers/find_customers via 'full record', though it never names those siblings.

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

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

Usage is only implied: an agent can infer this is the lookup for a single known customerId versus the list/find siblings. There is no explicit when-to-use, no exclusion of find_customers, and no statement of what to do if the ID is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only that the result may cover all fields or one, and says nothing about error behavior, missing fields, or result shape.

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

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

A single short, front-loaded fragment with no filler, though it is a sentence fragment rather than a complete statement of action.

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 three fully documented parameters the definition is nearly adequate, but with no output schema it should describe what the returned custom field values look like and how it relates to the definitions-listing sibling.

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% for all three parameters, so the schema already documents entity, entityId and fieldName. The description restates fieldName's effect without adding format or edge-case detail, making 3 the correct baseline.

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

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

The description names the resource (custom field values) and constrains it to a single entity, with an optional narrowing to one field. It lacks an explicit verb and never names the sibling list_custom_field_definitions, so the values-vs-definitions distinction is only implicit.

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

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

There is no statement of when to call this tool versus list_custom_field_definitions or any other sibling, and no prerequisites. The only conditional given ('a single one with fieldName') describes a parameter mode rather than when the tool itself applies.

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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description adds nothing on top of that — no return shape, no error behavior, no auth context — leaving it with zero incremental behavioral value.

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 three-word fragment is short, but this is under-specification rather than conciseness: it carries no actionable content and nothing is front-loaded because there is nothing to front-load.

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

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

For a simple single-parameter read tool with a complete schema and safety annotations, the bar is low, but the description still fails to say what a 'get' returns or how it differs from list_departments. The agent is left to reconstruct the tool's purpose entirely from structured 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% and the single parameter (departmentId) is documented in the schema, so the baseline of 3 applies. The description contributes no additional meaning about the ID's format, source, or constraints.

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

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

"One department." restates the title ("Get a department") rather than describing the operation; it names the resource but not a verb or scope. The singular form weakly implies a single-record fetch versus list_departments, but the description itself does no real distinguishing work.

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 mention of the sibling list_departments, and no indication that this is the ID-based lookup. An agent must infer the routing from the tool name and sibling list alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing on top — no note about what a miss returns, no auth/scope context, no rate limits — so it survives only because the annotations carry the load.

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

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

It is certainly short, but this is under-specification rather than conciseness — a five-word fragment that omits the verb and any retrievable detail. Brevity here costs information rather than saving the reader effort.

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 getter with full schema coverage and rich annotations, the structured data does most of the work, so a minimal description is tolerable. Still, with no output schema and no statement of what is returned or how the two required parameters combine, the definition is thinner than an agent needs to invoke it confidently.

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

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

Schema description coverage is 100%: both type (with its enum values enumerated) and deviceId are documented in the schema. Baseline 3 applies; the description adds no semantics beyond the schema, but nothing is missing either.

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

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

"One network-monitored device." is a noun fragment with no verb; it largely restates the name/title rather than stating an action. The word "One" weakly signals single-item retrieval versus the sibling list_devices, but an agent gets essentially no differentiation from the description text itself.

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

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

There is no guidance on when to use this tool, no prerequisites (e.g., that both type and deviceId must be known), and no reference to alternatives such as list_devices. The description contains no usage instruction at all.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value by naming the returned content (line items, issuer, recipient), though it omits error behavior for a missing invoice and any auth requirements.

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

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

A single short sentence that front-loads the resource and the returned payload. No filler, though it is terse to the point of leaving useful context unsaid.

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

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

No output schema exists, so the description reasonably carries the return-shape burden by naming the fields. However, for a lookup tool it should at least identify the input key (invoice number) and note behavior on a missing invoice.

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

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

Schema description coverage is 0% and the single required parameter invoiceNumber is never mentioned in the description, so it does not compensate for the coverage gap. The parameter name is self-descriptive, which keeps this from being a 1.

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

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

States the verb (get) and resource (invoice) plus the payload content — line items, issuer, recipient. It does not explicitly distinguish itself from the sibling list_invoices, but the singular resource and 'full invoice' phrasing implies a single-record fetch.

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

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

No when-to-use guidance, no prerequisite context, and no mention of the obvious sibling list_invoices as an alternative for browsing many invoices. The agent must infer the retrieval-by-ID use case entirely from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, so safety behavior is covered. The description adds genuinely new behavioral context about payload scope: it returns only the FIRST comment as the description and only the LAST end-user and technician comments, which prevents an agent from assuming it returns the full comment thread.

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

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

It is a single front-loaded phrase with no filler; every clause enumerates concrete returned data. It is a fragment rather than a full sentence, but it is efficiently sized for the amount of information conveyed.

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?

Because there is no output schema, the description rightly explains the return payload, and it does so well. However, it leaves the includeRelations parameter undocumented and gives no hint of how this tool relates to the overlapping ticket-listing siblings, so it is only adequately complete for a two-parameter retrieval tool.

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

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

Schema coverage is 50%: ticketId is documented in the schema while includeRelations has no description anywhere, and the description mentions neither parameter. It does not compensate for the coverage gap, leaving the meaning of includeRelations (which controls whether related records are returned) entirely unexplained.

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 identifies the specific resource and enumerates its returned content (description/first comment, last end-user and technician comments, SLA dates and durations), so the agent knows exactly what a ticket record contains. It does not, however, differentiate from overlapping siblings such as list_ticket_comments or get_ticket_work_hours, which fetch subsets of the same data.

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 prerequisites, and no mention of alternatives. With siblings like list_tickets, list_ticket_comments, and get_ticket_work_hours available, the description never states why an agent should call get_ticket instead of those.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value the annotations cannot: it discloses the shape of the payload (aggregate totals broken into billable/non-billable, with per-entry detail conditional on a flag) — useful given 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?

A single sentence with the primary payload front-loaded and the conditional detail trailing. Every clause earns its place; nothing is padded.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the aggregates and the entry list. Pagination behavior is left entirely to the schema, which is acceptable but slightly incomplete for a paginated 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 the schema already documents page, itemsInPage, ticketId and entries. The description's mention of 'entries=true' restates the schema's 'Also list each time entry' rather than adding format or defaulting nuance, so the baseline of 3 applies.

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

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

Names a specific resource and the exact data returned (billable/non-billable totals plus individual entries), which is more than a restatement of the title. It does not, however, contrast itself with the sibling get_ticket, so an agent must infer the split between the two.

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 entries=true clause hints at when to use the detailed mode, but there is no statement of when to prefer this tool over get_ticket or list_tickets, nor any prerequisite or exclusion.

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 the full safety profile (readOnly, idempotent, non-destructive, open world), so the bar is lower. The description adds the field set returned by default (name, customer, OS, online status, last seen, logged-in user), which is useful context absent an output schema, but says nothing about pagination behavior or what 'full' changes relative to the default summary.

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 and returned fields front-loaded and the optional filter trailing. 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?

For a zero-required-parameter list tool with no output schema, enumerating the returned fields is the key missing piece and it is supplied; annotations cover the safety profile. It is only slightly short of complete, lacking any hint about pagination scale or the summary-vs-full tradeoff.

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 (full, page, customerId, itemsInPage) are already documented. The description only reinforces the customerId filter, adding no new syntax, defaults, or limits beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource and clarifies the domain term ('monitored machines (Atera agents)'), and enumerates the returned fields. It does not distinguish itself from close siblings like list_devices or find_agents, so an agent must infer the boundary rather than being told it.

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

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

'Optionally only one customer' implies the customerId filter is the main scoping lever, which is mild usage guidance. There is no explicit when-to-use vs find_agents/get_agent/list_devices, and no stated conditions or 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: status is filtered by Atera, while severity/customer/agent filters scan up to maxPages pages. It does not cover rate limits or return format, but the added filtering behavior 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?

Two sentences, front-loaded with the core action followed by the key filtering behavior. There is no wasted wording, and the pagination/filter constraint is stated directly.

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

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

For a 9-parameter tool with no output schema, the description is minimal but adequate in places. It explains the scan behavior for some filters and relies on schema descriptions for pagination fields. However, it omits guidance on when to use the tool and does not fully clarify the relationships among page, limit, itemsInPage, and maxPages.

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 67%, so the schema documents most parameters. The description adds value for status, severity, customer, and agent filters by explaining that they scan up to maxPages pages, but it omits full, page, limit, and itemsInPage. It 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?

The description states a specific verb and resource: 'List alerts.' This distinguishes it from the singular sibling get_alert by name, though it does not explicitly call out the distinction. A clear purpose, but sibling differentiation is left to the 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?

The description says nothing about when to use list_alerts versus get_alert or other listing tools. It provides filter behavior, but no usage context, prerequisites, or alternatives are given.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that contacts are end users and that exact email/phone matching is server-side, which is useful context, but says nothing about pagination, result limits, or default ordering.

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

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

Two short sentences with zero waste; the core purpose is front-loaded ahead of the filtering clarification. Every sentence carries information.

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

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

Adequate for a read-only list tool whose annotations and full schema coverage carry the safety and parameter burden, and no output schema is needed. It is incomplete on sibling differentiation (find_contacts, get_contact) and pagination behavior, which an agent needs in a crowded toolset.

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

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

Schema coverage is 100%, so all five parameters are already documented in the schema. The description echoes email/phone filtering semantics but adds no new syntax, format, or constraint details 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+resource ('List contacts') and disambiguates the resource as 'end users'. However, it does not distinguish itself from the sibling find_contacts, which an agent must choose between for contact retrieval.

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 note that exact email/phone filtering is 'done by Atera' implies server-side filtering is supported, but there is no explicit when-to-use guidance and no routing to find_contacts or get_contact as alternatives. 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 already declare this as a safe, idempotent, open-world read, so the safety profile is covered. The description adds the contract-type enumeration but says nothing beyond the schema about pagination behavior or output size trade-offs.

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 with no filler, and the resource identity leads. It is arguably too terse to be maximally useful, but nothing in it is wasted.

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

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

For a simple read-only list tool with annotations covering the safety profile, this is minimally adequate. With no output schema and no statement of what a summary versus full item contains, an agent lacks guidance on the full=true trade-off beyond what the schema field text already says.

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 75%, with customerId being the undocumented parameter. The phrase "optionally for one customer" supplies that missing meaning, so the description partially compensates. The remaining parameters are already well described in the schema, so the baseline of 3 holds.

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

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

Names the resource (customer contracts) and enumerates the concrete types (retainer, block hours, hourly), which tells an agent exactly what is returned. It does not, however, distinguish itself from the singular get_contract sibling, so routing between the two is left to the 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?

"Optionally for one customer" implies the customerId filter is available but gives no when-to-use guidance, no mention of the get_contract alternative, and no indication of what to do when the caller does not know the customer id (find_customers/list_customers exist as siblings).

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety and idempotency profile is fully covered. The description adds the summary field list but nothing about pagination defaults, output size limits, or rate behavior beyond what the schema states.

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

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

Two short sentences, zero filler, with the returned fields and the sibling routing both front-loaded. 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 enumerates the default return fields and points to the search alternative. It omits pagination/return-shape behavior, but the schema carries the parameter side, so the definition is nearly complete for a simple 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 full/page/itemsInPage are already documented in the schema. The description only implies the summary vs. full field set via its field list and adds no syntax or default details beyond the schema. Baseline 3 applies.

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

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

States a specific verb (List) and resource (customers), enumerates the summary fields returned, and explicitly distinguishes itself from the sibling find_customers. An agent can tell this apart from search-style siblings without opening a schema.

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

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

Names the alternative explicitly ('Use find_customers to search by name'), giving a clear routing condition. It does not cover other nearby choices (get_customer for a single record, or when to set full=true), so it stops short of a full when/when-not guide.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no auth, pagination, or result-count behavior, but it does disclose the shape of the returned records, which is genuinely useful given 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?

A single short fragment with no wasted words, front-loading the resource and its fields. It lacks an explicit verb, but the name supplies it and the sentence remains scannable.

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 zero-parameter, read-only list tool with full annotation coverage, the description is nearly sufficient: it characterizes the returned fields, partially compensating for the absent output schema. The only meaningful gap is disambiguation from 'get_custom_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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing to clarify beyond the empty schema.

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

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

The description names the resource (custom field definitions in Atera) and enumerates what each definition contains (name, data type, target entity, allowed values), which goes beyond the title. However, it does not distinguish this tool from the very similarly named sibling 'get_custom_fields', leaving the agent to guess which one to call.

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 mention of prerequisites, and no routing to or away from the near-duplicate sibling 'get_custom_fields'. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds nothing beyond that – no mention of pagination behavior, the large-output tradeoff of `full`, or result ordering/scope.

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

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

It is short and front-loaded with zero filler, but it is under-specified rather than efficiently concise – a two-word fragment that omits any verb or useful framing.

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

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

With no output schema and a purely noun-phrase description, an agent gets no sense of what a department record contains, how results are paged, or how this relates to get_department. The definition is too sparse for a tool in a large multi-entity API surface.

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

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

Schema coverage is 100% and each of the three parameters has a clear inline description, so the schema carries the burden. The description contributes nothing extra (e.g., default page size context or when to use `full`), 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?

"Customer departments." is a bare noun phrase that essentially restates the tool name/title without adding a verb or scope. It doesn't distinguish this list tool from the sibling get_department or explain what a "customer department" is.

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 indication of when to call this versus get_department or the other list_* tools. The agent must infer from the name alone that this enumerates departments.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is fully covered without description help. The description adds the meaningful scope fact that these are network-monitored devices rather than agents, which is useful disambiguation. It says nothing about pagination defaults, the cost of the 'full' flag, or result ordering.

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

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

A single sentence, front-loaded with the resource and immediately followed by the exclusion that prevents the most likely mis-selection. No filler and nothing to trim.

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

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

For a simple paginated read tool with a fully documented schema and complete read-only annotations, the description covers the one thing structured fields cannot: what this collection is versus the agent collection. No output schema exists, but the return shape is trivially inferable from the 'full' flag and page parameters.

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 (type, page, itemsInPage, full) are already documented, including the enum values and the warning that 'full' produces much larger output. The description's enumeration of generic/TCP/SNMP/HTTP merely echoes the enum. Baseline 3 is appropriate.

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

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

The description names a specific resource ('network-monitored devices') and enumerates the four kinds (generic, TCP, SNMP, HTTP), so the agent knows exactly what set is returned. It also draws a boundary against a close sibling (agents installed on machines), which is the main source of ambiguity. The listing verb itself only appears in the name/title, not the description.

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 an explicit exclusion — 'not the agents installed on machines' — which effectively routes the agent toward list_agents for machine-installed agents. That is a real when-not statement rather than implied usage. It stops short of stating positive conditions (e.g., 'use this when you want to audit monitored network endpoints') or naming list_agents by 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?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that—it does not explain pagination defaults, the effect of full=true, or result ordering, so it adds little value.

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

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

It is a single short fragment with no wasted words, but the fragment is under-specified and not front-loaded with an action. Conciseness is present, but structure suffers because it never states what the tool does.

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 only loosely indicates returned fields while omitting pagination behavior and the purpose of the 'full' parameter. The sibling list/get pattern (e.g., list_contracts vs get_contract) is not addressed, leaving the agent without enough context to choose this tool 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 description coverage is 100%, so all three parameters (full, page, itemsInPage) are already well documented. The description lists invoice fields but does not clarify parameter semantics beyond what the schema provides, which is the baseline expectation at full schema coverage.

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

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

The description names the resource (invoices) and hints at fields, but it is a noun phrase rather than a specific verb+resource statement. It does not distinguish this list operation from the sibling get_invoice tool, leaving the agent to infer the action from the tool name.

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

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

There is no guidance on when to use this tool versus get_invoice or list_contracts. It also does not mention the default pagination behavior or when to use the 'full' parameter, so the agent receives no usage context.

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, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds one genuine insight: with a query the tool scans across product, keywords, category, section and content, which hints at the cost/scope of a scan. It still says nothing about pagination behavior or result ordering.

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

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

Two short sentences, no filler. The scan-scope detail is the only substantively useful content and it is not buried.

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

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

With six fully documented parameters, annotations covering the safety profile, and no output schema, the definition is adequate but thin. It does not explain the paged maxPages/itemsInPage interaction or what a returned summary item looks like, which are the main remaining ambiguities for a 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 a baseline of 3 applies, but the description goes beyond the schema by naming the exact fields the 'query' parameter matches against (product, keywords, category, section, content) — a detail the schema omits. The other five parameters are left to the schema.

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

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

The description opens with a bare noun phrase, 'Knowledge base articles,' which essentially restates the name and title rather than stating a verb. The second sentence does clarify the tool's filtering behavior, but the core 'what it does' (list/retrieve articles) is only implied.

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

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

There is no guidance on when to use this tool versus siblings such as get_department or list_tickets, nor any statement of prerequisites or when it should not be used. The query sentence implies a search use case but never frames it as a decision criterion.

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 readOnly=true, idempotent=true, destructive=false and openWorld=true, so the safety profile is fully covered structurally. The description adds the semantic distinction between the two modes (modification-date vs status-change), which is genuinely useful, but says nothing about pagination behavior, output size, or result ordering.

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

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

Two tight sentences with no filler, and the primary filter semantics are front-loaded ahead of the usage example. The parenthetical mode names are slightly clipped, but nothing is wasted.

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

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

With six parameters, no output schema, and a 'full' flag that dramatically changes payload size, the description does enough to orient the caller but omits output shape, the summary-vs-full tradeoff, and pagination defaults that an agent must read from the schema. Adequate, not complete.

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

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

Schema description coverage is 100%, so every parameter including the mode enum and the 'since' UTC/ISO constraint is already documented in the schema; baseline 3 applies. The description restates the mode default and that 'since' applies to last_modified, but adds no format or interaction 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 and resource ('Tickets modified since a date ... or whose status changed') and names the two filtering modes, so the agent knows exactly what population is returned. However, it never distinguishes itself from the sibling list_tickets tool, which an agent must otherwise infer means 'all tickets regardless of modification'.

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 'Good for "what happened today / since Monday"' gives an implied use context, which is more than nothing. But it names no alternative (list_tickets, get_ticket) and gives no exclusions or prerequisites, leaving the agent to guess when this beats the plain ticket list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds nothing beyond that: it does not mention pagination behavior, the effect of the 'full' flag on response size, default page sizes, or ordering. For a read-only list tool with annotations present, this is below the modest bar.

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 one short clause with no wasted words, so it is concise. However, it is under-specified rather than efficient, and it never states a verb or action, leaving the sentence closer to a label than a useful definition.

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

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

This is a simple paginated list tool with only four parameters and a read-only annotation profile, so the burden on the description is modest. The schema documents paging and the full-output flag, and annotations cover safety, but the description supplies no return-shape, ordering, or filtering context. Adequate 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 coverage is 75%: 'full', 'page', and 'itemsInPage' are documented in the schema, while 'kind' (the required enum) has no schema description. The phrase 'products or expenses' effectively documents the two enum values, compensating for that one gap. With most parameters already covered by the schema, a baseline 3 is appropriate.

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

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

The fragment 'Billing rates: products or expenses.' names the resource and the two subdivisions (which map to the kind enum), so an agent can infer this lists billing rates. However, it reads as a noun-phrase restatement of the title rather than a verb+resource statement, and it omits any scope or verb. It is a weak but not tautological purpose.

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

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

There is no guidance about when to use this tool versus siblings like list_invoices, list_contracts, or get_invoice, and no mention of prerequisites or alternatives. The description offers implied context only through the resource name. No when-to-use or when-not-to-use information is present.

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds only that the returned data includes attachment names and links, without discussing pagination, permissions, or response structure.

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 a single concise sentence with no wasted text. It is front-loaded with the resource, though its brevity contributes to gaps in usage guidance and behavioral 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 simple one-parameter read-only list tool, the description gives minimal but usable context: it names the resource and return contents. It omits pagination behavior, empty-result handling, and any distinction from related ticket subresources, which keeps it from being fully complete.

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

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

Schema description coverage is 100%, and the single ticketId parameter is documented in the schema as 'Ticket ID'. The description adds no additional meaning about the parameter, so the baseline of 3 is appropriate.

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

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

The description identifies the resource as ticket attachments and adds that names and links are returned. However, it largely restates the tool name/title and does not explicitly state the listing action or distinguish it from siblings beyond the resource.

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

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

There is no guidance on when to use this tool versus alternatives such as get_ticket, list_ticket_comments, or get_ticket_work_hours. The agent must infer that this is the tool for attachments from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful content-level context by disclosing the fields returned (author, date, internal flag, text), but says nothing about pagination behavior, ordering, or the significance of the internal flag.

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

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

A single tight sentence that front-loads the resource and lists the salient returned fields without waste. It is appropriately sized for a simple read tool.

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

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

For a read-only list tool with rich annotations and 100% schema coverage, no output schema is needed and the description adequately conveys what comes back. It could be stronger by noting pagination (the schema exposes page/itemsInPage) or the meaning of the internal flag, but it is broadly complete.

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

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

Schema description coverage is 100%, so full, page, ticketId, and itemsInPage are all documented in the schema, including defaults and max values. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description names the resource (a ticket's conversation) and enumerates the returned fields (author, date, internal flag, text), which clearly identifies it as a comment-listing tool distinct from siblings like list_ticket_attachments. It lacks an explicit verb, relying on the title, and doesn't explicitly differentiate from get_ticket, but 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 when-to-use guidance, no mention of prerequisites (a valid ticketId), and no reference to alternative tools such as get_ticket or list_ticket_attachments. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuinely new behavioral trait not in structured data: ordering is not guaranteed newest-first. It doesn't discuss result volume tradeoffs beyond what the schema states.

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

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

Three short sentences, zero filler: capability first, filters second, ordering caveat and alternative last. 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 does the work of describing the returned summary fields, which is the main completeness gap for a list tool. Pagination defaults and limits are left to the schema, which is acceptable, though the absence of any note about page-size caps or total counts is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by enumerating exactly what the summary projection contains — the schema only says 'every field of each item instead of a summary', leaving the default payload shape undefined. That enumeration is real information an agent cannot get from 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?

Specific verb+resource ('List tickets') with the summary field set enumerated inline (number, title, status, priority, customer, end user, technician, dates) and the filterable dimensions named. It also explicitly distinguishes itself from list_modified_tickets, so an agent can route without opening schemas.

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 explicit selection context: filter by status and/or customer, and 'Newest first is not guaranteed: use list_modified_tickets for recent activity' names the alternative plus the condition that selects it. It stops short of advising when to use `full` versus the summary view or when to page.

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