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

No annotations are provided, so the description carries the full burden. It clearly notes a key behavioral limitation: SuperOps does not expose CPU, memory, or disk figures on the asset record, and it directs the agent to an alternative. This is valuable context, though it does not discuss read-only status, permissions, or rate limits.

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

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

Two tightly written sentences. The first front-loads the purpose and enumerated data, while the second cleanly handles the limitation and alternative. No redundant or filler content.

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

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

For a simple one-parameter read tool with no output schema, the description fully compensates by listing the returned fields and setting expectations about unavailable data. Nothing essential is missing for an agent to call and interpret the result.

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 lone parameter (assetId) is already fully documented in the schema. The description implies a specific asset is required but adds no format or syntax detail beyond the schema. Baseline 3 is appropriate 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 ('Get detailed information for a specific asset') and enumerates the exact data returned (hardware identity, OS, network, agent version, patch status). It clearly distinguishes from list-type siblings by specifying 'a specific asset' and explicitly routes missing CPU/memory/disk data to a different tool.

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

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

Explicitly states when to use this tool (fetching detailed info for one asset) and when not to use it (CPU, memory, or disk figures), naming the alternative tool (superops_custom_query) and the specific queries needed. This gives the agent a clear decision boundary.

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

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

With no annotations, the description carries the full burden and does well: it discloses the non-obvious AND-combination semantics of the filters and the unusual pagination contract where listInfo.hasMore is null (never false) at the end. It omits permission/auth or rate-limit context, but for a read-only list tool the pagination quirk is the highest-value behavioral detail.

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

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

Three sentences, zero padding, and the core purpose is front-loaded before the filtering and pagination guidance. Every sentence carries information an agent needs.

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 steps in to explain the pagination return signal (listInfo.hasMore). Combined with the high schema coverage for parameters, an agent has enough to call it correctly, though the overall response shape is only partially sketched.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description earns above it by adding the filter-combination logic (multiple filters are ANDed) that the schema does not state. It doesn't add per-parameter format detail, but that is already covered by the schema.

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

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

States a specific verb and resource ('List assets (endpoints)') with the product context ('in SuperOps.ai RMM'). The parenthetical clarifies that 'assets' means endpoints, which distinguishes it from siblings like superops_assets_software and superops_assets_patches.

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?

Tells the agent how to invoke it ('Supply any combination of status, platform and clientId; several filters are combined with AND'), which is clear operational context. However, it never names when to prefer this over sibling tools such as superops_assets_get or the software/patches variants.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that installationStatus and severity are joined with AND, but says nothing about pagination behavior, permissions, or result ordering despite a page/pageSize interface.

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

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

Three sentences, front-loaded with the core purpose, followed by filter-combination semantics and then the alternative routing. No filler and 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?

For a read-only listing with no output schema and no annotations, the description is largely complete: it lists returned fields and names the alternative tool. It stops short of describing pagination or result limits, which is the only notable 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 extra credit by explaining non-obvious semantics the schema does not express: how installationStatus and severity combine, and the distinct grouping of approval status versus install state.

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

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

States a specific verb (Get) and resource (patch status and patch details for a specific asset) and enumerates the exact returned fields (title, KB numbers, category, severity, approval status, installation status). It also names the sibling alternative (superops_custom_query with getAssetPatchStatus), so an agent can distinguish it without opening either schema.

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

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

Explicitly routes the agent: use this for the per-patch list, and use superops_custom_query with getAssetPatchStatus for a one-word roll-up of overall health. The condition that selects the alternative is stated, not left to inference, and the AND combination of filters is clarified.

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?

No annotations are supplied, so the description carries the full burden. It implies a read-only retrieval and lists the fields returned, which is useful, but it never mentions that results are paginated or that search only matches the software name, nor any permission or rate-limit considerations.

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

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

One sentence, front-loaded with the verb and resource, and the field list is packed directly after the colon with zero filler.

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

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

With no output schema, the description usefully substitutes by enumerating the returned fields (name, version, install date, bit version, install path). Only the pagination behavior and the scope of the search filter are left unaddressed, and both are covered by the input schema.

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

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

Schema description coverage is 100%, with page, search, assetId and pageSize all documented in the schema itself, so the baseline is 3. The description adds no parameter-level detail (e.g., that search is substring/case-insensitive) beyond what the schema already states.

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

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

The description names a specific verb ('Get') and resource ('software inventory') and enumerates the returned fields, so the agent knows exactly what the tool fetches. It does not, however, differentiate itself from the nearby superops_assets_patches or superops_assets_get siblings, which have similarly shaped 'for a specific asset' semantics.

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 or when-not-to-use guidance and no named alternative. The agent must infer from the word 'software' that this is the sibling to pick over assets_patches; nothing in the text routes 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?

With no annotations, the description carries the transparency burden. 'Get' implies a read-only operation, and 'detailed information' suggests the return is a rich client object. However, it does not disclose what happens for an invalid/unknown accountId, rate limits, or the exact fields returned.

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, front-loaded sentence with no filler. Every word adds clarity about the target and lookup key.

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

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

For a single-required-parameter read tool with full schema coverage, the description is nearly complete: the agent can correctly call it with accountId. The only gap is that 'detailed information' does not enumerate the returned fields, and there is no output schema to fill that 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?

The input schema covers 100% of the parameter with 'The unique account ID of the client,' so the baseline is 3. The description only restates the accountId parameter ('by their account ID') without adding format, source, or validation details.

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

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

The description uses a clear verb and resource: 'Get detailed information for a specific client.' The qualifier 'specific client' and 'by their account ID' help separate it from collection-style siblings like clients_list and clients_search, though it does not name those alternatives explicitly.

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

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

It states a definite context: use this when you have a client's account ID and need detailed information for that one client. It does not mention exclusion criteria or the list/search siblings, but the precondition is clear from the phrase 'by their account ID.'

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?

No annotations are provided, so the description carries the full burden. It does disclose pagination behavior and the stage/status AND semantics, which is genuinely useful, but says nothing about read-only nature, permission requirements, rate limits, or whether tenant-renamed stages/statuses affect filtering outcomes beyond the schema's own note.

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

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

Three short sentences with no filler, and the core action is front-loaded. Slightly more could be trimmed since the pagination and filter sentences largely duplicate schema content, but structure is clean.

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 no annotations, the description should do more work: it does not describe the shape of returned client records or whether pagination metadata (total counts) is returned. Pagination and filtering are covered, but an agent calling it blind still lacks return-value expectations.

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, pageSize, stage, and status in detail. The description's restatement that supplying both stage and status narrows results adds only marginal value over the schema's own 'Combined with status if both are given' note. Baseline 3 applies.

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

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

States a specific verb and resource: 'List clients (accounts) in SuperOps.ai', clarifying that 'clients' and 'accounts' are the same entity. However, it never distinguishes itself from the sibling superops_clients_search, leaving the agent to infer which list-style tool to pick.

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

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

Provides implicit usage context via pagination and the stage/status combination rule, but offers no when-to-use guidance or explicit alternative (e.g., use search when you need text matching). The agent must infer the boundary with superops_clients_search on its own.

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

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

No annotations are provided, so the description carries the full behavioral burden. It explains the matching rule ('term appears in either' name or email domain) and the domain-fragment use case, but does not state read-only safety, permissions, or result/pagination behavior. That is only partial disclosure.

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

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

Two tight sentences with zero filler, and the matching rule is front-loaded. The size is appropriate for a simple search 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 3-parameter search tool with complete schema descriptions, the description covers query semantics well. However, with no output schema, it omits return shape and pagination behavior, leaving the agent to infer the response structure.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds concrete meaning beyond the schema by explaining that a domain fragment will match the account that owns it, which clarifies the query parameter's practical behavior.

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 ('clients') plus the searchable fields (name, email domain). It does not name sibling superops_clients_list, so sibling differentiation is left to inference, but the matching semantics distinguish it from a plain list.

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

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

No explicit when-to-use or when-not guidance, and the alternative superops_clients_list is not mentioned. The search-by-name/domain phrasing implies usage, but routing between this and list/get siblings is left to the agent.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions 'write operations,' which implies mutation, but it does not warn about potential destructiveness, irreversibility, required permissions, or side effects of executing arbitrary GraphQL mutations. This is a significant gap for a tool that can run any mutation.

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

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

The description is two short sentences with no redundancy. The core action is front-loaded, and the usage qualification follows efficiently. Every word earns its place.

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

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

For a low-level, open-ended mutation tool with no annotations and no output schema, the description is too thin. It does not explain what the response will look like, warn about the risks of arbitrary mutations, or clarify that variables are optional. An agent receives only the barest sketch of how to use this safely or effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new meaning about the parameters beyond what the schema already states; it merely labels the action as a mutation. It is adequate but provides no additional semantic value.

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 clear verb ('Run'), resource ('SuperOps.ai API'), and operation type ('GraphQL mutation'), and specifies it is for advanced write operations. It does not explicitly name the sibling superops_custom_query, but the mutation/query distinction is implicit in the GraphQL terms, giving adequate differentiation from standard tools.

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

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

The phrase 'For advanced write operations not covered by standard tools' conveys when this tool should be used and implies that standard tools should be the first choice. It does not explicitly enumerate alternatives or state when not to use it, falling slightly short of explicit when/when-not guidance.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure, but it only states the high-level action. It does not disclose whether queries are read-only, what happens on invalid GraphQL, error behavior, rate limits, or authentication requirements. The term 'query' hints at a read operation but is not explicit.

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 concise sentences with no filler. The first sentence front-loads the core action, and the second states the use case. Every sentence contributes meaningful 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?

This is a raw GraphQL execution tool with no annotations and no output schema, so the description needs to supply more operational context to be complete. It lacks guidance on response shape, error conditions, query scope limitations, or how it relates to custom_mutation. The current description is adequate for identifying the tool but not for safely invoking it in advanced scenarios.

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

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

Schema description coverage is 100%, with the schema already explaining 'The GraphQL query string' and 'Variables to pass to the query'. The description adds context about the API and advanced use, but it does not provide additional parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description states a specific action ('Run a custom GraphQL query') and scope ('against the SuperOps.ai API'). It also differentiates from standard sibling tools by noting it is for advanced use cases not covered by them. The distinction from the sibling custom_mutation is implied by the GraphQL query/mutation vocabulary, which is sufficient.

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 'For advanced use cases not covered by standard tools' clearly indicates when to use this tool and implies that standard tools should be preferred for ordinary operations. It does not explicitly mention custom_mutation as the alternative for write operations, so the guidance is good but not exhaustive.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the tool returns tool names and descriptions, and it clarifies the non-gating nature ('All tools are callable at any time — this is a help/discovery aid, not a prerequisite'). This is meaningful behavioral context beyond the schema.

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

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

The description is two sentences, each earning its place: the first states purpose and output, the second removes a common misconception about prerequisite behavior. It is front-loaded and contains no filler.

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

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

For a single-parameter discovery tool with no output schema, the description covers purpose, return content, and a key behavioral caveat. It does not detail the exact response structure, but that is not necessary for an agent to invoke and interpret a help/discovery tool.

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

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

Schema coverage is 100% and the single domain parameter has detailed descriptions for each enum value, so the schema fully explains parameter semantics. The tool description itself adds no additional parameter meaning, which is appropriate given the rich schema.

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

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

The description states a specific verb ('Discover'), a resource ('available SuperOps.ai tools'), and a scope ('by domain'). It also explicitly states what is returned ('tool names and descriptions'), making it clearly distinct from the operational sibling tools like superops_tickets_get or superops_clients_list.

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

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

The description positions this as a help/discovery aid, making its intended use clear. It also explicitly states it is not a prerequisite for other tools, which prevents an agent from incorrectly treating navigation as a required step. It does not explicitly list alternatives, but the siblings are operationally different.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool shows status, with no detail on what states are reported, whether this is a live check or cached data, or what the response contains. This is minimal and leaves behavioral expectations vague.

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 short phrase with no wasteful content. The key resources are presented immediately and clearly for a zero-parameter status 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?

The tool is simple and has no parameters, but there is no output schema and no explanation of what 'credentials status' or 'available domains' means in practice. An agent knows roughly what it will see, but not the shape or semantics of the returned data, which limits completeness.

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 has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies because the description need not compensate for undocumented parameters.

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

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

The description names a specific operation ('show') and two concrete resources ('credentials status' and 'available domains'). It is clear enough to distinguish this from data-retrieval and mutation siblings, though it doesn't explicitly contrast itself with similar tools like superops_test_connection.

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

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

No guidance is provided about when to call this tool versus alternatives. The description does not mention typical use cases, prerequisites, or exclusions, so an agent must infer when 'status' is needed.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the filtered-list implementation quirk, the exact return shape (contact details, role as {roleId, name}, group roster array), and that designation, businessFunction, team and reportingManager are null unless the tenant assigns them. It also proactively rules out skills, ticket counts and response-time metrics, which prevents wasted follow-up calls.

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

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

Three sentences, all load-bearing: purpose first, implementation caveat second, return shape and unavailable fields last. No padding or restatement of the name.

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

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

There is no output schema, so the description must convey return semantics, and it does so completely, including the null-unless-assigned fields and the explicitly unavailable metrics. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 100% and there is a single required parameter, so the schema already documents technicianId as the unique technician user ID. The description adds no format or syntax detail beyond that, which is the correct baseline 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 ('Get detailed information for a specific technician by their user ID'), and explicitly differentiates itself from the list sibling by explaining SuperOps has no single-technician endpoint and this filters the list. An agent can distinguish it from superops_technicians_list without opening either schema.

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

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

Clear context for retrieval of one technician's details, and the implementation note implies the list tool is the alternative for multiple records. It does not explicitly say 'use technicians_list to enumerate' or state prerequisites, so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does so unusually well: it discloses the exact return shape (ID and name only), that no description/member count/roster is exposed, and that the endpoint is neither paginated nor filterable. These are precisely the behavioral traits an agent needs and cannot infer elsewhere.

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

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

Three tight sentences, front-loaded with the purpose, then the return shape and limitations, then the relationship to the technician groups field. Every sentence earns its place with no filler.

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

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

No output schema exists, and the description compensates by stating exactly what is returned (ID and name) and what is not available. For a zero-parameter, unpaginated read tool, nothing an agent needs is missing.

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

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

The tool takes zero parameters (0 params, schema coverage 100%), so per the rubric the baseline is 4. There is nothing to document and the description correctly adds no parameter detail.

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

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

States a specific verb (List) and resource (technician groups/teams in SuperOps.ai), and the resource is clearly distinct from siblings like superops_technicians_list and superops_technicians_get. An agent can tell what this returns without opening the schema.

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

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

The description explains the practical use case: these groups match the groups field on a technician, so a group ID from here identifies a technician's group. That is clear contextual guidance, though it stops short of explicitly naming alternatives or stating when NOT to call 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?

With no annotations, the description carries the full burden and delivers: it discloses the absence of active/inactive flags, ticket counts, and last-login data, and warns that listInfo.hasMore is null (never false) so callers must page against totalCount. These are non-obvious behavioral traits that cannot be inferred from the schema.

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

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

Front-loads purpose and sorting, then layers search behavior, return shape, and pagination caveats. Dense but nearly every sentence carries distinct information; slightly long but justified by the missing output schema.

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

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

There is no output schema, so the description must carry return semantics, and it does: role as {roleId, name}, groups as {groupId, name}, and which fields are null unless assigned. Combined with pagination guidance, it is complete enough to call correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning by specifying that 'search' matches as a substring against both name and email, and that results are sorted by name. It adds value beyond the schema field descriptions.

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

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

States a specific verb and resource ('List technicians (agents) in SuperOps.ai, sorted by name') and clarifies the sort order. The scope (name/email substring search) distinguishes it from the plural sibling tools like superops_technicians_get and superops_technicians_groups.

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

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

Explicitly routes overflow filtering to 'superops_custom_query' for filters beyond a name search, giving a clear when-to-use alternative. It doesn't address when to prefer superops_technicians_get for a single record, but that distinction is obvious 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool takes no arguments, that it queries 'this SuperOps tenant,' and that it returns id/name pairs — useful behavioral context for a lookup. It does not discuss whether results are cached, whether they can be empty, or any tenant/permission scoping, but for a zero-arg read-only catalog listing, the essential behavior is conveyed.

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

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

Front-loaded with the primary purpose in the first sentence, followed by the mapping rationale and a concrete usage chain. Slightly long, but every sentence earns its place by explaining what is returned, why those values matter, and how to use the result. No filler.

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

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

For a zero-arg lookup with no output schema, no annotations, and absent schema parameter details, the description fully compensates: it enumerates the categorical data returned, clarifies the {id, name} shape, explains the foreign-key relationship to technician fields, and directs the agent to the consuming tool with a concrete filter example. An agent has everything needed to call and use it correctly.

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

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

The tool has zero parameters, so per the rubric the baseline is 4. The description reinforces this with 'Takes no arguments,' which is accurate and helpful, though no additional parameter semantics are possible.

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?

Starts with a specific verb+resource: 'List the roles, teams, designations, business functions and technician groups.' It enumerates exactly what entity types are returned and clarifies the output shape as {id, name}. This distinguishes it from siblings like superops_technicians_list and superops_technicians_groups, which presumably return technicians or only groups, not this catalog of lookup values.

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

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

Explicitly states when to use it: to 'turn a name a user gave you ... into the ID SuperOps filters on,' and then names the downstream tool superops_custom_query with a concrete condition example (getTechnicianList accepts a condition on the role and groups attributes). This is a complete when/why/next-step chain, leaving no ambiguity about its role as a name-to-ID resolver.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool tests the connection using credentials, but it does not disclose whether this is a read-only operation, what happens on success or failure, or whether any side effects or network calls are made beyond the basic implication of a test.

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 clear sentence with no filler. It immediately communicates the tool's purpose and the prerequisite of configured credentials, making every word valuable.

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

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

Given the tool's simplicity — no parameters, no output schema, no complex behavior — the description is largely complete for an agent to understand the operation. It could be improved by clarifying the expected result format or relationship to 'superops_status', but the core use case is sufficiently covered.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific detail, but none is needed because the input schema is empty and fully covered.

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 clearly states a specific action ('Test the connection') and the target resource ('SuperOps.ai API'), making the tool's purpose obvious. It does not explicitly differentiate itself from the sibling tool 'superops_status', which may also involve connectivity checks, so it stops short of a 5.

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

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

The phrase 'using configured credentials' implies the tool is meant for verifying API connectivity with existing credentials. However, there is no explicit guidance about when to use this tool versus alternatives like 'superops_status' or when not to use 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?

No annotations are provided, so the description carries the full burden. It mentions that notes can be internal or public, but this visibility detail is already covered in the schema's isPublic parameter description. It does not disclose other behavioral traits such as permission requirements, notification side effects, or whether notes can be edited or deleted.

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

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

Two short sentences, front-loaded with the action and followed by the key public/internal distinction. There is no wasted wording.

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

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

The tool is simple, the schema is fully documented, and there is no output schema to explain. The description conveys the main purpose and the public/internal distinction. It is not fully complete because it omits usage guidance and behavioral side effects, but the core context is sufficient for invocation.

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

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

Schema description coverage is 100%, so all three parameters are already well documented. The description mentions internal/public notes, which corresponds to isPublic, but adds no syntax, format, or mapping detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Add a note to a ticket.' It clearly distinguishes this action from sibling operations like superops_tickets_update and superops_tickets_log_time, which modify or log rather than add notes.

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

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

Usage is implied by the action itself, and the second sentence adds context about internal versus public visibility. However, it does not explicitly state when to prefer this tool over alternatives such as updating a ticket or logging time, nor does it give exclusions or prerequisites.

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

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

No annotations exist, so the description carries full burden. It usefully discloses one real constraint—status/priority/category/subcategory are free-text and must match tenant-configured values—but omits permissions/auth needs, side effects, whether the ticket is auto-assigned, and any response semantics for a 15-param mutation.

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, purpose front-loaded in the first clause and the constraint note second. Every sentence earns its place with no filler.

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

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

With 15 parameters, no output schema, and no annotations, the description is thin: it never says what the call returns (e.g., the created ticket ID) or what happens on failure. Parameter documentation is complete via schema, so it is minimum-viable but not sufficient for a mutation of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters richly (including enum and per-field tenant notes). The description's note about free-text match requirements marginally reinforces four fields but adds little 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?

States a specific verb and resource ('Create a new ticket in SuperOps.ai'), which plainly contrasts with siblings like superops_tickets_update, superops_tickets_get, and superops_tickets_list. It is clear, though it never names an alternative to further sharpen the distinction.

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

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

There is no when-to-use/when-not guidance and no mention of alternatives such as tickets_update for existing tickets or add_note for follow-ups. The agent must infer the appropriate context (a genuinely new ticket) from the verb 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?

No annotations are provided, so the description must carry behavioral disclosure. It communicates a read/get operation but adds no detail on response structure, error behavior (e.g., unknown ticket ID), permissions, or what 'detailed information' includes.

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 concise sentence with no filler; key information is front-loaded and every word contributes.

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 get-by-ID tool, the description and schema are enough for selection and invocation. However, with no output schema and no annotations, the phrase 'detailed information' is vague about what the agent will receive, which leaves some uncertainty.

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%: ticketId is described as 'The unique ticket ID'. The description's 'by its ID' reinforces this but adds no new semantic detail, so it meets the baseline.

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

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

States a specific verb ('get'), a resource ('ticket'), and the selection criterion ('by its ID'). This clearly distinguishes it from list-oriented siblings like superops_tickets_list.

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

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

The 'by its ID' phrasing establishes when to use the tool: when the caller has a known ticket ID and wants details. It does not explicitly name alternatives or exclude list/search flows, but the context is sufficient for most agents.

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?

No annotations are supplied, so the description carries the full burden. It usefully discloses pagination via page/pageSize and the AND-across-filters / OR-within-array matching rule, which is non-obvious behavior. However, it says nothing about permission requirements, default sort order, or whether a total count is returned, leaving notable behavioral gaps for an unannotated tool.

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

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

Three tight sentences with zero filler. The core action is front-loaded, pagination is stated next, and the filter-combination rule follows; every sentence carries distinct 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 six-parameter list tool with no output schema and no annotations, the description covers the essentials an agent needs: scope, paging, and filter-combination logic. It stops short of describing the returned ticket shape, default ordering, or total-count behavior, which would complete the picture.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by specifying the boolean combination semantics: every provided filter must match, while status and priority accept any of the listed values. That disambiguates how multiple array values interact, which the schema alone does not state.

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

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

The description opens with a specific verb+resource pair ('List tickets in SuperOps.ai'), so the agent immediately knows this is a read/list operation on the tickets collection. It does not, however, explicitly distinguish itself from siblings like superops_tickets_get or superops_tickets_search, so it falls short of the top band.

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: listing tickets is self-evidently what the tool is for, and the filter-combination sentence hints at when each filter applies. There is no explicit statement of when to choose this over superops_tickets_get, superops_custom_query, or a search-style sibling, and no exclusions or prerequisites are given.

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

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

With no annotations, the description carries the full burden. It usefully discloses that quantity is recorded against the service item's unit (typically hours) rather than raw minutes, which is a non-obvious behavioral trait. However, it omits mutation side effects, permission requirements, and defaults, leaving significant gaps for a write operation.

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

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

Two tightly written sentences with zero waste. The core action is front-loaded, followed by a critical nuance about quantity semantics.

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 nine-parameter mutation tool with no annotations and no output schema, the description is fairly thin. It covers the key quantity nuance but does not address side effects, required permissions, or default behaviors that an agent should understand before invoking a write operation.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description reinforces the quantity/unit semantics for qty but adds no new parameter meaning beyond the schema. Baseline 3 is appropriate 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?

The description states a specific verb and resource: logging a worklog entry against a ticket. This is clearly distinct from siblings like add_note or update. However, it does not explicitly differentiate itself from those siblings or name the alternative tool for time logging.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. The context is implied by 'log a worklog entry' but the description does not help an agent decide between this and other ticket mutation tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the resolutionCode-only constraint on the resolution path, which is genuinely useful, but says nothing about partial-update semantics (are omitted fields left unchanged?), required permissions, validity of status transitions, or reversibility for what is a mutation tool.

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

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

Two sentences, zero filler, with the core capability front-loaded and the disambiguation constraint second. Every clause carries information the agent needs.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description covers what can be changed and the resolution nuance, but omits partial-update behavior, permission requirements, and any indication of success/failure response. 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 description coverage is 100%, so the baseline is 3, and the description earns an increment by clarifying that only the tenant-configured resolutionCode belongs here while free-text resolution content must go elsewhere. It does not clarify the assignment pair (technicianId vs techGroupId) or the category/subcategory dependency beyond what the schema states.

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

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

States a specific verb (update) plus resource (existing ticket) and enumerates the mutable facets: status, priority, assignment, category. The second sentence distinguishes this tool from superops_tickets_add_note, so an agent can route without opening either schema.

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

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

Gives an explicit when-not with the alternative named: free-text resolution notes go to superops_tickets_add_note, and only a configured resolutionCode may be set here. It does not cover update vs. superops_tickets_create or prerequisites, but the boundary case that most easily causes misuse is handled.

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