zscaler-mcp-server

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

Annotations already declare readOnlyHint: true, and the description repeats 'read-only,' which is consistent. It adds value by disclosing the two modes (list and fetch by ID) and implies no mutations. However, it does not describe pagination, rate limits, or what 'lite' returns, but for a read tool with annotations, this is adequate.

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 sentence that conveys the core purpose and two modes with zero waste. It is front-loaded and succinct, earning high marks for efficiency.

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 4 parameters, no output schema, and minimal annotations, the description is too sparse. It omits the 'search' parameter entirely and does not clarify the semantics of 'read_lite' vs 'read'. While the query parameter has a detailed schema description, the other three parameters remain ambiguous. The description does not provide enough context for an agent to confidently use all parameters 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 only 25% (only query is described). The tool description barely addresses parameters: it implies action (list all/lite) and dict_id (fetch by ID) but omits 'search' entirely and does not explain the difference between 'read' and 'read_lite'. With three undocumented parameters, the description should provide more semantic context, but it does not.

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 'Read ZIA DLP dictionaries' with specific verbs (list, fetch) and resource. It distinguishes the two modes: list all/lite or fetch by ID. No sibling tool covers DLP dictionaries, so it stands out. The read-only note reinforces the intent.

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

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

The description implies usage: list all/lite for general enumeration or fetch by ID for a specific dictionary. It does not explicitly mention alternatives or when not to use it, but given its uniqueness among siblings, context is clear. It lacks explicit guidance on conditions for choosing 'read' vs 'read_lite'.

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=true and openWorldHint=false, so the description's 'read-only' phrasing is consistent and not contradictory. It adds behavioral context about listing vs fetching by ID, but does not explain what 'lite' means or describe the shape of results. This is acceptable but not rich, especially with no output schema.

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

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

The description is a single, front-loaded sentence that communicates the core purpose and modes without wasting words. Every phrase 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 simple read-only tool with four parameters and no output schema, the description covers the main entry points but does not explain the 'lite' variant, the search parameter, or return format. The query parameter's schema description adds important caveats, so the overall package is workable but incomplete for an agent needing to use all available options 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?

The schema describes only the query parameter (25% coverage), so the description carries more burden. It clarifies the action parameter ('list all/lite') and engine_id ('fetch one by ID'), but completely omits the search parameter. The query parameter's detailed schema description compensates partially, but the search parameter remains unexplained, leaving a meaningful 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 uses a specific verb ('Read'), names the resource ('ZIA DLP engines'), and clearly distinguishes the two modes: list all/lite or fetch one by ID. It is distinct from sibling tools like get_zia_dlp_dictionaries by naming a different 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?

The description provides clear context for when to use the tool and when to use its internal modes ('list all/lite' vs 'fetch one by ID'). It does not explicitly name alternative tools for DLP dictionaries, but the sibling list makes this less critical. No exclusions or alternative tools are mentioned, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds '(read-only)' which is redundant. It does add the two operational modes (list/fetch), but lacks details on pagination, error behavior, or response format. With annotations covering safety, the description provides minimal extra behavioral context.

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, front-loaded with the key action and resource. Every word contributes, with no filler or repetition.

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 9 parameters, no output schema, and low schema description coverage, this minimal description is insufficient. It does not address return values, parameter relationships, the distinction between 'list' and 'read_lite', or error handling, leaving the agent under-informed for correct 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 only 11% (only 'query' is described), and the tool description does not compensate. It mentions 'filters' and 'by ID' but does not map to the 9 parameters or clarify ambiguous ones like 'action' (read_lite) or 'limit_search'. The description adds little meaning beyond the schema itself.

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 the action ('Read') and resource ('ZIA user departments'), and specifies two modes: 'list with filters' or 'fetch one by ID'. This distinguishes it from sibling tools like get_zia_users and get_zia_user_groups by resource and operation.

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

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

The description implies clear usage contexts: use when you need to list departments with filters or retrieve a single department by ID. It does not explicitly name alternatives or provide when-not-to-use guidance, but the two-mode framing offers sufficient context for selection.

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 description adds 'read-only' which aligns with the readOnlyHint annotation but provides no additional behavioral context. It does not disclose pagination, result ordering, or any potential side effects beyond the read-only nature. Given the annotation already covers safety, the description adds minimal value here.

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, front-loaded sentence that efficiently conveys the tool's core functionality without any fluff. 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?

Given the tool has 9 optional parameters and no output schema, the one-line description is insufficient. It fails to mention return format, pagination behavior, default sorting, or any constraints, leaving the agent without critical operational context for correct 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?

The description maps three usage scenarios to parameters (group_id for 'fetch by ID', name for 'find by name', and no params for list) but does not explain the other six parameters (page, page_size, sort_by, sort_order, defined_by, search). With schema description coverage at only 11%, the description should compensate more for the missing parameter semantics, but it only partially does.

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 the tool reads ZIA user groups and enumerates three modes: fetch by ID, find by name, or list. This is specific and distinguishes it from sibling tools like get_zia_users and get_zia_user_departments, which target different resources.

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?

While the description indicates what the tool does, it offers no guidance on when to choose this tool over alternatives such as zid_get_user_groups or zid_get_user_groups_by_name. There is no mention of prerequisites, mutually exclusive modes, or when a particular mode is appropriate.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'read-only'. It adds the list-vs-by-ID behavioral distinction but does not disclose pagination behavior, result shape, or what happens when no filters are supplied. With annotations covering the safety profile, this is acceptable 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?

The description is a single front-loaded sentence that immediately identifies the resource and operation. Every word earns its place; 'read-only' is slightly redundant with the annotation but not harmful.

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 7 optional parameters, no output schema, and a large sibling tool set, a one-sentence description is insufficient. It does not explain return values, pagination, filter combinations, or the distinction between list and by-ID behavior beyond the bare minimum. The query parameter's rich guidance lives only in the schema, not the description.

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

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

Schema description coverage is only 14%, so the description needed to compensate, but it only generically says 'optional filters' and 'fetch one by ID'. It does not explain dept, name, group, page, page_size, or how user_id relates to the other parameters. Only the query parameter has meaningful schema documentation.

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

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

The description uses a specific verb ('Read') and resource ('ZIA users'), and clearly distinguishes the two modes: list with optional filters or fetch one by ID. This is enough to separate it from sibling user-related tools like zid_get_user or get_zia_user_departments.

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 clearly states when to use the tool: for listing ZIA users with optional filters or fetching a single user by ID. It does not explicitly name alternatives or exclusions relative to sibling tools, but the context is clear enough for a simple read operation.

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 tool description's '(read-only)' aligns with and reinforces the annotation readOnlyHint=true, with no contradiction. The description adds the '(inspection)' clarification, but the most substantive behavioral disclosure (the snake_case vs. camelCase warning and 'call once without query' advice) lives in the `query` parameter schema, not the tool description.

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 12-word sentence communicates the action (list), the resource (ZPA App Protection profiles), a disambiguation ((inspection)), a filtering option (by name), and safety (read-only). Every word earns its place — true conciseness.

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 leaf-level read-only list tool with no output schema and all-optional parameters, the description is nearly complete. Combined with the extensive `query` parameter documentation, an agent is well-equipped. Minor gaps: no explicit note on pagination behavior, default limits, or when to use this 'profile' tool vs. its 'rule' or 'credential' counterparts.

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

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

Schema description coverage is only 25% (solely `query`), which is well below the 80% threshold, so the description must compensate. The phrase 'filter by name' covers the `name` parameter, and the `query` parameter gets an exemplar schema description. However, `page` and `page_size` have no documentation beyond their self-evident names, and the description provides no additional semantics for them.

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

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

The description uses a specific verb-resource pairing ('List ZPA App Protection (inspection) profiles') and adds the parenthetical '(inspection)' to disambiguate the resource, plus clarifies the read-only safety profile. It clearly states what the tool does. However, it doesn't explicitly distinguish itself from closely named siblings like `zpa_list_app_protection_rules` or `get_zpa_posture_profile`.

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?

'or filter by name' gives a concrete invocation pattern, and '(read-only)' signals it's safe to call without side effects. There is no when-to-use vs. alternatives, no exclusions, and no mention of exclusions like pagination defaults — the usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, and the description merely restates 'read-only', adding no new behavioral information. It does not disclose return format, pagination behavior, the effect of page_size/expand_all, or any operational constraints beyond param values (application_type enumeration is parameter semantics rather than behavior). No contradiction with 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 sentences, no wasted words, and the core purpose is front-loaded. The brevity is efficient, but it borders on under-specification — for a 6-parameter tool, one could argue the description is too sparse rather than appropriately concise.

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 6 parameters, 17% schema coverage, and no output schema, the description leaves most of the tool's surface undocumented. Beyond application_type, nothing explains search, page_size, expand_all, or microtenant_id. For a moderately complex filtering tool, this is incomplete.

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

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

Schema description coverage is only 17% (1 of 6 params described). The description adds value for application_type by enumerating its valid values (BROWSER_ACCESS, INSPECT, SECURE_REMOTE_ACCESS) — useful since the schema lacks an enum. But search, page_size, expand_all, and microtenant_id remain entirely undocumented by both schema and description, failing to compensate for the low 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 states a specific verb+resource+scope: 'Retrieve ZPA application segments filtered by application type'. The name already conveys 'by type' filtering, and the description confirms the purpose and the three valid application_type values. However, it does not differentiate from sibling tools like zpa_list_application_segments, zpa_list_application_segments_ba, and zpa_list_application_segments_pra, which serve similar listing purposes.

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

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

No guidance on when to use this tool versus the several sibling segment-listing tools (zpa_list_application_segments, zpa_list_application_segments_ba, zpa_list_application_segments_pra, zpa_get_application_segment). The description gives no when-to-use, when-not-to-use, or alternative recommendations.

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 annotation already declares readOnlyHint=true, so the description's '(read-only)' adds no new information. However, it does describe the behavioral distinction between listing all records versus looking one up by name or ID, which is not explicit in the annotations. This helps an agent understand the tool's operational modes but doesn't dive into details like pagination behavior or error cases.

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, well-structured sentence that front-loads the core action and resource. It efficiently conveys the two primary modes of operation without any unnecessary fluff. 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?

The description is adequate for a tool with six optional parameters but leaves gaps. It explains the primary use cases but doesn't clarify the semantics of 'search' or default pagination behavior (e.g., default page size). The interaction between 'query' and other parameters is also unspecified, though that is partially addressed in the 'query' parameter's own description.

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

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

Schema description coverage is only 17% (only 'query' has a schema-level description). The main description partially compensates by mapping 'name' and 'ID' to lookup semantics, which would otherwise be ambiguous. However, it fails to clarify the meaning of 'search' (fuzzy vs. exact) and the role of 'page' and 'page_size' beyond inference from their names.

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 strong verb ('Read'), identifies a specific resource ('ZPA enrollment certificates'), and concisely conveys two modes: listing all or looking up by name/ID. This clearly distinguishes it from sibling tools like 'zpa_get_pra_credential' or 'zpa_list_lss_configs' by resource type.

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 offers no explicit 'when to use' guidance, no mention of alternatives, and no exclusions (e.g., 'for PRA credentials use get_zpa_pra_credential'). It's implied the tool is for enrollment certificates, but this is redundant with the name and does not help an agent decide between this and other ZPA-specific read tools in the large sibling set.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with '(read-only)'. The description adds the behavior of exact-name filtering and the optional query parameter's client-side filtering behavior, including a warning about field name casing. This adds value beyond the annotations, though it does not detail pagination 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 sentence that is front-loaded with the primary action and resource, then adds the filtering option and read-only note. It is concise with no wasted words, and the schema's query parameter description is detailed but appropriately placed in the schema rather than the 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?

Given the tool's simplicity (list/filter profiles), the description is complete enough. It covers the main use case, the read-only nature, and the filtering behavior. The query parameter's detailed schema description handles the complex filtering logic. No output schema exists, but the description implies the return of profile records, which is sufficient for this simple 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%: the 'name' parameter has no description, but the tool description explains it filters by exact name. The 'query' parameter has a rich description in the schema, and the tool description adds context about its purpose. The description compensates for the missing 'name' parameter documentation, so the agent understands both parameters' semantics.

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

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

The description clearly states the tool lists ZPA Cloud Browser Isolation (CBI) profiles and can filter by exact name, explicitly noting it is read-only. This distinguishes it from sibling tools like zpa_list_isolation_policy_rules and get_zpa_isolation_policy_rule, which deal with policy rules rather than profiles.

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

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

The description implies usage: list all profiles or filter by exact name. It does not explicitly state when to use this tool versus alternatives, but the read-only nature and the specific resource (CBI profiles) provide clear context. No exclusions or alternative tool names are given, but the purpose is clear enough for an agent to select it appropriately.

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 read-only behavior is already declared via annotations (readOnlyHint=true), and the description redundantly repeats 'read-only', which adds no new information. It does disclose the capability to look up by ID or name, which is a behavioral detail beyond the annotations. However, it doesn't mention pagination, error handling, or return format. Given the annotations cover the safety profile, this is adequate but not rich.

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 fluff. It front-loads the core action and resource. It is concise and easy to parse, but it could benefit from a brief note on pagination or alternative usage. Still, it achieves conciseness without sacrificing primary clarity.

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 tool with 5 parameters and no output schema, this description is underspecified. It lacks information about result pagination (page, page_size), the effect of the query parameter for filtering, and return structure. While the annotations confirm read-only status, the description does not guide the agent on how to use the tool effectively beyond the basic list/lookup. The detailed query parameter description in the schema partially mitigates this, but the overall description remains incomplete.

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 description mentions 'by ID or name', hinting at the profile_id and name parameters, but does not explain page, page_size, or query parameters. Schema description coverage is only 20%, so the description should compensate, but it adds minimal parameter meaning. The query parameter has a detailed schema description, but that's from the schema, not the tool description. The description fails to clarify how pagination or filtering works, leaving ambiguity.

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 the tool's function: listing ZPA posture profiles or retrieving one by ID or name. It specifies the resource (posture profiles) and the actions (list or lookup), and distinguishes it from other similar tools by naming the specific ZPA entity. The read-only qualifier adds clarity about the operation's nature.

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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions for using list vs. lookup, or trade-offs against other profile-related tools. The short sentence leaves the agent to infer usage solely from the tool name and description, which is insufficient for complex decisions.

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 read-only nature is already declared in annotations and repeated in the description. The description adds the optional IdP scoping behavioral detail, but does not mention pagination, search behavior, or potential error conditions. Given the annotation covers safety, score is moderate.

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 that front-loads the main action and scope, with no wasted words. Perfectly concise and well-structured.

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 has 5 parameters, no output schema, and limited schema descriptions. The description only covers the IdP scoping, leaving 'search' and pagination behavior unexplained. This makes it incomplete for an agent to fully understand the tool's capabilities and limitations.

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

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

Schema description coverage is only 20% (only 'query' has a description). The description adds meaning for 'idp_name' via 'scoped to a named IdP', but fails to clarify 'search', 'page', or 'page_size'. Since low coverage requires the description to compensate, this is insufficient.

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 the tool's action ('List ZPA SAML attributes') and adds optional scoping to an IdP. This distinguishes it from sibling tools like get_zpa_scim_attribute and get_zpa_scim_group.

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

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

The description implies use for listing SAML attributes with optional IdP scoping, but does not provide explicit when-to-use vs alternatives or exclusions. It lacks a direct comparison to sibling tools such as get_zpa_scim_attribute.

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

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

The readOnlyHint annotation already communicates safety; the description's '(read-only)' is consistent and adds a small amount of clarity. The genuine value-add is disclosing the dual list-vs-fetch-by-ID behavioral modes, which the annotation doesn't convey. However, it omits details about pagination behavior, response format, or the substantial query-filtering foot-guns (which live in the schema, not the tool description). No contradiction — the description and annotation agree.

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 clean sentence front-loaded with the primary verb 'List', followed immediately by the secondary mode. Every word earns its place — zero fluff, no redundant phrasing. The parenthetical '(read-only)' is the only add-on and it's informative. Exemplary economy.

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 6-parameter tool with no output schema, the description covers the basic operational modes but leaves real gaps. It doesn't address pagination parameters, the search parameter's semantics, or anything about the return value shape — especially important since no output schema exists. The critical snake_case-vs-camelCase warning is buried in the schema, not surfaced here. The query param's schema description helps, but the tool-level description does the minimum.

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 schema description coverage at only 17%, the description must compensate — and it partially does. It ties 'named IdP' to idp_name (the sole required param) and 'fetch one by ID' to attribute_id. But page, page_size, and search receive zero semantic context in the description, and the query param (despite its excellent schema-level documentation) is unaddressed. Adequate for the two most important parameters, thin on the rest.

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

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

Clear imperative verbs 'List' and 'fetch' with a specific resource 'ZPA SCIM attributes' and scope 'for a named IdP'. It distinguishes from the very similar sibling get_zpa_saml_attribute by the 'SCIM' resource qualifier and implies attribute vs. group semantics vs. get_zpa_scim_group. Loses a point for not naming sibling alternatives explicitly, but is much stronger than the typical getter.

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 dual-mode phrasing ('List... for a named IdP, or fetch one by ID') implies when to use which mode but never states explicit when-to-use vs. alternatives ('if you need SAML attributes, use...'). The '(read-only)' note and the IdP-scoping are useful context. Guidance is implied, not explicit — no exclusions or named alternatives.

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

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

The description repeats the read-only annotation but adds no new behavioral details such as pagination behavior, error handling, or permission requirements. It is consistent with annotations but does not go beyond them in disclosing side effects or edge cases.

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 that efficiently conveys the core functionality without redundancy. It is well-structured and easy to parse.

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 description adequately covers the essential operations and read-only nature. It does not mention output format or pagination, but for a simple read operation, it provides sufficient context for an agent to decide when to call it. The lack of explicit alternative guidance slightly reduces 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 description maps scim_group_id to 'by ID' and idp_name to 'under a named IdP', adding meaning to those parameters. However, it does not explain page, page_size, or search (beyond the schema's existing JMESPath description). Schema coverage is low, and the description only partially compensates.

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 the tool's two primary functions: fetching a single ZPA SCIM group by ID or listing all groups under a named IdP. It explicitly includes 'read-only' and distinguishes this resource from other ZPA objects, making it unambiguous.

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

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

The description explains the two modes of operation (by ID or by IdP name) but does not explicitly contrast this tool with sibling tools like get_zpa_scim_attribute or zpa_list_pra_credentials. It lacks explicit 'when to use this vs. alternatives' guidance, though the resource specificity provides some implicit 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?

The description adds the capability of looking up by ID or name beyond annotations. Annotations already specify read-only, and the description repeats that, which is redundant. It does not disclose pagination or return format, but with readOnlyHint true and no contradictory info, this is adequate.

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 that immediately conveys the main actions. No filler, and the read-only note is useful. Perfectly sized.

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 5 parameters and no output schema, the description is insufficient. It only covers list vs lookup but leaves pagination, query semantics, and parameter purposes unexplained. The absence of an output schema increases the need for description to indicate what is returned, which it does not do. Incomplete for a tool 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 only 20% (query param). The description hints that name and network_id are used for lookup, but does not explain page, page_size, or the query behavior. It does not compensate for the low coverage; the agent would need to rely on bare parameter names. The query param has its own detailed description, but that's not part of the tool's description.

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

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

The description clearly states it lists ZPA trusted networks or looks one up by ID or name. This is a specific verb+resource and distinguishes the tool from others targeting different resource types (e.g., rules, segments). Comprehensive enough for the agent to understand the primary actions.

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 clarifies the two modes (list all vs. look up by ID/name), making it evident when to use this tool. It does not explicitly mention alternatives or exclusions, but the sibling tools are for different resource types, so the niche is clear. A more explicit 'use list for all, lookup for specific' would be better, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with "Read-only (GET, no tenant mutation)". More importantly, it adds critical context: "returned values ARE sensitive short-lived credentials — treat them like passwords". This goes beyond annotations and alerts the agent to handle the output securely.

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 crisp sentences that front-load the core purpose, followed by essential safety and prerequisite details. Every sentence earns its place with zero fluff.

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?

Covers purpose, OTP types, sensitivity, and the prerequisite. Lacks details about the return format or structure, but no output schema exists, and the tool is a straightforward GET. The udid/device_id ambiguity is a minor gap but doesn't prevent basic use.

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?

Input schema has 0% description coverage, so the description must compensate. It explains `udid` as the device identifier and points to zcc_list_devices, but it omits `device_id` entirely, leaving its role unclear. Also, the description says udid is required while the schema marks it optional (default null), creating a contradiction that undermines parameter understanding.

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 the tool's function: "Get the OTP bundle for a ZCC device" and enumerates the OTP types (logout / exit / uninstall / disable). This specific verb+resource combination distinguishes it from sibling tools like zcc_list_devices.

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

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

Provides a clear prerequisite: "Requires the device's `udid` (from `zcc_list_devices`)"—telling the agent exactly where to obtain the required identifier. It does not explicitly mention when not to use it or explain the alternative device_id parameter, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds value by enumerating the fields included per row (identity, OS, agent version, etc.) and the udid relationship, which helps the agent understand the response shape.

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

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

The description is two sentences long, with the purpose stated first, followed by row content details. Every sentence adds information without redundancy.

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

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

The description covers the response contents well but omits pagination details, filter semantics, and any note about the query parameter. Given the tool's 5 optional parameters and missing output schema, there are notable gaps, though the read-only annotation and field list provide a solid baseline.

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

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

Schema description coverage is only 20%, with only the query parameter documented. The tool description provides no additional explanation for page, page_size, os_type, or username, leaving the agent to infer their meanings from parameter names alone.

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

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

The description uses a specific verb 'List' with a clear resource 'ZCC enrolled devices', and explicitly marks it read-only. This distinguishes it from sibling tools like zdx_list_devices and zia_list_devices.

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

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

The description gives clear context about what records are returned and points to a specific downstream use (zcc_get_device_otp). However, it does not explicitly mention alternative tools or exclusions, though the ZCC prefix and content differentiate 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?

The annotation readOnlyHint=true and the description's 'Read-only' are redundant, but the description adds contextual behavior by noting results are company-scoped. It does not disclose pagination behavior, response format, or any other side effects beyond read-only.

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, front-loaded sentence without fluff. Minor deduction for 'Read-only' being redundant with the annotation, but it is otherwise concise and well-structured.

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

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

For a list tool with no output schema, the description should mention return values, pagination, or scoping details. It only states the resource and read-only nature, leaving the agent without enough information to predict the response shape or handle pagination 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 only 25% (query param), and the tool description does not mention any parameter semantics. The query param has a detailed schema description, but page, search, and page_size are undocumented, and the description does not compensate for the low 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 uses a specific verb ('List') and explicitly names the resource ('ZCC forwarding profiles'), adding scope with '(by company)'. This distinguishes it from sibling list tools like zcc_list_devices and zcc_list_trusted_networks, though it does not explicitly contrast with ZPA forwarding policy 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?

No guidance is provided on when to use this tool versus alternatives. The parenthetical '(by company)' hints at scoping but does not explain when this tool is preferred over other list tools or any exclusions.

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

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

The description says 'Read-only,' which matches the readOnlyHint annotation and is not contradictory. It adds the minor scoping detail 'by company,' but does not disclose return behavior, pagination, or potential quirks beyond what annotations already establish.

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 extremely concise and front-loaded, stating the core purpose in one sentence. The second sentence 'Read-only' is redundant with the annotation, but the overall structure is efficient and free of unnecessary 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 read-only list tool with no output schema, the description is too minimal. It does not mention return format, pagination behavior, or how the search/query parameters interact. The detailed query schema note helps, but the tool-level description leaves important context unresolved.

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-level description adds no parameter meaning. The query parameter is well-documented in the schema itself, but page, search, and page_size have no explanation in either the schema or the description. With low schema coverage (25%), the description should compensate but does not.

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 the action ('List'), the resource ('ZCC trusted networks'), and the scope ('by company'). It is specific enough to distinguish this from the many sibling list tools, even though it does not explicitly name an alternative.

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, nor any mention of pagination, search behavior, or prerequisites. The description only states what it does, not how or when 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?

The annotations already provide readOnlyHint=true, so the 'Read-only' statement is redundant but reinforces the behavior. The description adds detail about the scope (ZCELL_CUSTOMER_ID) and the specific data returned, which goes beyond annotation basics. It does not mention any other side effects or requirements, but for a read-only get tool, this is adequate given the annotations cover safety.

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: the first states the purpose, and the second elaborates on the return data and scoping. It is front-loaded with the main action and resource, followed by concise details. Every sentence adds value without fluff or redundancy, making it highly efficient.

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 has no parameters, no output schema, and simple read-only behavior, the description provides a solid list of what is returned (identity, activation state, platform, regions, SIM counts, usage, linked cloud metadata). It does not mention error conditions, permissions, or pagination, but for a get-customer operation these are less critical. The description is complete enough for an agent to understand the tool's purpose and output.

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?

There are zero parameters in the schema, so the description carries the full burden of explaining what the tool uses as context. It explicitly mentions 'Scoped by ZCELL_CUSTOMER_ID', which tells the agent that the operation is implicitly scoped to the logged-in customer, adding meaning beyond the empty input schema. With no parameters, the description appropriately provides the necessary context without needing to explain individual 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 clearly states the action (Get) and the resource (logged-in Zscaler Cellular customer's profile and SIM totals). It enumerates specific data fields returned (identity, activation state, platform, regions, SIM counts, current usage, linked ZIA/ZPA metadata), which distinguishes it from sibling tools like zcell_list_sims or zcell_get_sim_details that focus on individual SIMs or lists.

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 indicates this tool returns the logged-in customer's profile and SIM totals, and mentions it is scoped by ZCELL_CUSTOMER_ID, implying it is used when you need overall customer context. It does not explicitly name alternatives or exclusion criteria, but the clear scoping and focus on customer-level data provide sufficient context for when to use it versus more granular SIM-focused 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?

Explicitly states 'Read-only', aligning with the readOnlyHint annotation, and lists returned fields (ICCID, IMSI/IMEI, status, etc.), providing transparency about data content beyond the annotation.

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 redundant phrasing; the first states the core purpose and the second adds read-only status and return field list, making it well-structured and efficient.

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

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

With no output schema, the description compensates by listing the return fields. It is complete for a simple getter, though it omits potential error conditions or usage caveats.

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 only parameter icc_id is described as the identifier used to fetch the record ('by ICCID'), clarifying its purpose beyond the schema's minimal 'Icc Id' label.

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 clearly states the action ('Get') and resource ('full Zscaler Cellular record for one SIM'), and specifies the key identifier (ICCID), distinguishing it from list and location-group sibling 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?

Implies usage when you need full details for a single SIM identified by ICCID, contrasting with list tools. Lacks explicit 'when to use' vs alternatives, but the context is clear enough.

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 description states 'Read-only' matching the readOnlyHint annotation and goes further by explaining the extra data returned, providing transparency beyond the annotation.

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 concise, two sentences, with no redundant information, and gets straight to the point.

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?

It sufficiently explains what the tool does and what it returns (geo-fence, policies, membership buckets) without an output schema. It could be slightly more detailed but is adequate for a get 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?

The only parameter group_id is present in the schema but the description does not elaborate on its meaning or format. Since schema coverage is 100%, baseline is 3, and no additional meaning is added.

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 the tool gets one SIM location group and distinguishes it from the list variant by adding detailed fields like geo-fence definition, anomaly policies, and ICCID membership buckets.

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

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

The description implies when to use this tool (when detailed info beyond summary is needed) and indicates it is read-only. It does not explicitly mention alternatives but the context is clear.

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

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

The description reinforces the readOnlyHint annotation with 'Read-only' and details the return shape (one row per policy with the fields listed) and the lookback window behavior. While it echoes the annotation context, it adds value by naming exact output fields beyond the schema, which helps with chaining. It misses on noting pagination behavior (also missing from the schema), but the query params for page/size imply it.

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

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

The description is three sentences and front-loads the purpose, then context, then chaining—a clear funnel structure. Every sentence adds value. It's arguably the ideal length for a list tool with rich annotations, as it reiterates the read-only nature and gives actionable details without bloat.

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

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

For a list tool with an existing output schema (though minimal) and 5 parameters, the description covers the full lifecycle: input (`days`), output fields, and downstream consumption (`id` chaining). The only gap is a canned example showing `days=30` usage or common combinations, but the description already goes further than typical list tools by preemptively warning about the `query` parameter's gotchas. It confidently covers the 'model the agent's mental model' bar.

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 `query` parameter description is exceptional—it goes beyond the schema with concrete JMESPath examples, warns about the snake_case/camelCase mismatch, and even provides a troubleshooting tip (call without `query` to see field names). The `days` lookback is documented in the description text. While `policy_type` lacks enum values, the schema provides a title and type, and the description's explicit warning for `query` more than compensates for this small 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 uses a specific verb+resource ('List Zscaler Cellular anomaly policies') and clearly distinguishes this from sibling tools by enumerating the returned fields (id, name, type, enabled state, run status, applied SIM location groups, violation count) and referencing the sibling log and violations tools by name. It's immediately clear this lists policy summaries rather than logs or violations.

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 provides clear context ('Use the returned `id` with the anomaly-policy logs and violations tools'), which serves as light chaining guidance and implicitly explains when to use this tool vs. relevant siblings. However, it doesn't explicitly state when NOT to use the tool or reference search/alternatives by exact naming beyond the high-level 'anomaly-policy logs and violations tools', which is a minor miss given the sibling list shows many similar 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?

The annotation already provides readOnlyHint, and the description adds meaningful behavioral detail about what the log contains: enable/disable/run history with status, message, and timestamp. It does not discuss pagination or error/rate-limit behavior, but for a read-only listing tool the disclosed return content is sufficient context.

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 and fully front-loaded with the action and resource. There is no filler, repeated schema content, or unnecessary 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 read-only, single-policy log tool with four parameters and no output schema, the description covers the key output semantics and the primary required parameter. It lacks explicit pagination/default behavior, but those optional parameters and the strong query docs in the schema make this reasonably 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?

The description adds meaning to `policy_id` by identifying it as the policy whose log should be fetched, and the schema already provides rich guidance for the `query` parameter. However, `page` and `size` receive no semantic explanation, and with schema description coverage at 25%, the description could do more to compensate for these undocumented optional 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 uses a specific verb and resource: 'List the activity log for one Zscaler Cellular anomaly policy.' It also states the returned content (enable/disable/run history with status, message, timestamp), which clearly distinguishes it from sibling tools like zcell_list_anomaly_policies and zcell_list_anomaly_policy_violations.

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 clearly scopes the tool to a single `policy_id` and explains it is for viewing activity logs, giving the AI solid context on when to invoke it. It does not explicitly name alternatives or say 'use zcell_list_anomaly_policies to get policy_id first,' but the intended usage is reasonably clear.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds useful behavioral context by stating that it returns 'policy rows carrying violation data over a `days` lookback window,' clarifying the output granularity beyond the annotation alone.

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

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

The description is three short sentences with the purpose front-loaded. It contains no filler and each sentence earns its place: purpose, behavior, and sibling guidance.

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

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

With no output schema, low parameter coverage, and five parameters, the description is not complete enough. It explains the high-level purpose and points to the sibling tool, but it omits what `policy_id` refers to, how pagination works, and what the returned 'policy rows' actually contain.

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

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

Schema description coverage is only 20%, and the description does not compensate. It mentions `days` as a lookback window, but provides no meaning for the required `policy_id` or for `page`/`size`. The `query` parameter has a detailed schema description, but the description itself adds little parameter-level understanding.

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 and resource: 'List the ICCIDs that violated a Zscaler Cellular anomaly policy.' It clearly distinguishes itself from the sibling zcell_list_iccid_violations, which is described as drilling into per-event detail for a specific ICCID.

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 explicitly says 'Use zcell_list_iccid_violations to drill into the per-event detail for a specific ICCID,' providing a clear alternative. It also frames the tool as read-only and scoped to a days lookback window, which tells the agent when this listing tool is appropriate.

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 description explicitly states 'Read-only' and confirms with the readOnlyHint annotation. It also discloses that before/after data blobs are omitted from the rows, which is a behavioral detail not apparent from the schema. No contradictions with annotations.

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

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

The description is concise—two sentences—and clearly structured. It states the primary action, the read-only nature, the output format summary, and the key parameters without unnecessary verbosity.

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 description provides a summary of what is returned (who, what, when, operation) and notes the omit of blobs, which is useful given no output schema. It does not mention pagination or error cases, but for a search tool, the core context is adequately 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?

Only the 'query' parameter is described in the schema (JMESPath). The description mentions 'days' window and 'operation/object/visibility filters', covering days, operation_type, object_id, object_name, object_type, and visibility, but leaves page, size, and modified_by_user_id unexplained. Given 10 optional parameters, the description only partially compensates for the low 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 clearly states the tool's purpose: searching Zscaler Cellular audit-log entries. It specifies the resource (audit logs), the action (search), and key details (read-only, curated rows, lookback window). This effectively distinguishes it from list-only sibling tools like zcell_list_audit_metadata.

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 when to use the tool: for searching audit logs with optional filters (operation/object/visibility) over a specified time window. It also mentions read-only nature and omission of before/after blobs, giving context. However, it does not explicitly contrast with alternative list/search tools, so it's clear but not perfectly proactive.

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 mark readOnlyHint; description adds that it returns operation types and object types and their purpose in the search tool. No contradictions.

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; 'Read-only.' is redundant with the annotation but not excessive. The rest is directly informative.

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 states what is returned (operation types and object types) and how they relate to the search tool. The query parameter is fully documented in the schema. Adequate for a simple read-only metadata listing.

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 covers 100% of the single `query` parameter with detailed JMESPath guidance; tool description adds no param-specific info, 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?

Description names a specific resource ('Zscaler Cellular audit filter vocabulary') and clearly states it returns valid operation types and object types for `zcell_list_audit_customers_search`, distinguishing it from sibling list tools.

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

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

The description implies when to use it: to discover the valid operation types and object types to pass to `zcell_list_audit_customers_search`. It doesn't explicitly exclude other uses or name alternatives, but its purpose is clear enough within the context of the sibling tools.

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

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

The readOnlyHint annotation already establishes the safety profile, and the description reinforces it with 'Read-only.' It adds useful behavioral context by specifying that individual violation events are returned with event type, zone, and timestamp, and by clarifying the per-ICCID and policy_id scoping. No contradictions with annotations.

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

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

The description is concise and front-loaded: the first sentence states the exact action, and the second adds scope and return details without repetition or filler. Every sentence earns its place.

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

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

Given that there is no output schema, the description adequately covers the main return fields and key parameters. It lacks explicit details about ordering, pagination, or default lookback behavior, but the schema supplies the days default and the read-only annotation covers safety, making this reasonably 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?

The tool description compensates for the low 25% schema coverage by explaining the roles of iccid, policy_id, and days in relation to the returned violations. The only schema-described parameter, query, is already thoroughly documented in the schema itself, so its absence from the description is acceptable.

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

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

The description uses a specific verb ('List') and identifies the exact resource: anomaly-policy violation events for one ICCID, scoped by policy_id and a days lookback window. It also names the returned event fields (event type, zone, timestamp), clearly distinguishing it from broader sibling tools like zcell_list_anomaly_policy_violations.

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 clearly indicates this tool is for retrieving violation events for a single ICCID under a given policy_id over a lookback window, which implies the appropriate use case. It does not explicitly name alternatives or exclusions, so it falls short of a 5, but the context is unambiguous.

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

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

Annotations already provide readOnlyHint: true, and the description reinforces this with 'Read-only.' It adds behavioral context by stating it returns curated event rows with specific fields, and exposes the lookback window and optional filtering/pagination, which goes beyond annotations. No contradictions.

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 that front-load the core purpose, then list return fields and parameters. Every sentence adds value with no redundancy or fluff.

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 tool with 7 parameters and no output schema, the description provides a useful summary of returned fields but omits some parameters (exclude_apn_config) and the shape of complex objects. It is not fully complete but covers the essential search/return behavior, making it adequate but not exceptional.

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

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

Schema coverage is only 14%, so the description must compensate. It adds meaning to 'days' as a lookback window, and mentions filter_by, sort_by, and pagination, but does not explain exclude_apn_config or the structure of sort_by/filter_by objects. The 'query' parameter is well-explained in the schema itself, so partial compensation exists but gaps remain.

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 the tool searches Zscaler Cellular network/session events over a lookback window, naming a specific verb, resource, and scope. It also lists the curated return fields, distinguishing it from sibling tools like zcell_list_sim_usage_by_sim or zcell_list_anomaly_policies.

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

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

The description implies usage through 'Search' but provides no explicit when-to-use or when-not-to-use guidance, nor alternatives. With many sibling tools, the lack of differentiation beyond the name leaves the context ambiguous, though the purpose is clear enough to infer basic usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds 'Read-only.' (redundant) but also specifies the response content: each configured region, BC/AC status blocks, and MAP A-C/B-C link statuses. This goes beyond annotations and gives useful behavioral context without contradiction.

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

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

The description is two sentences, front-loaded with the main purpose and followed by return details. There is no filler; even the 'Read-only.' duplication is minimal and harmless. Perfectly sized and structured.

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 no output schema, the description covers the core purpose and high-level return format. However, it leaves `bc_size` entirely undocumented and does not mention any field-level details or pagination/error behavior. Adequate but with a clear gap on the second parameter.

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

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

Schema description coverage is only 50%, and the description adds no parameter meaning at all. The `query` parameter is well-documented in the schema, but `bc_size` has no schema description and the tool description never mentions it. This leaves a significant gap that the description fails to compensate for.

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 starts with 'List Zscaler Cellular configured regions with their operational status', using a specific verb and resource with clear scope. It distinguishes itself from sibling zcell_list_regions by focusing on operational status and enumerating the returned status blocks (BC/AC, MAP link statuses).

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 usage is implied: use this tool to fetch operational status of configured regions. However, it does not explicitly state when to prefer this over similar siblings like zcell_list_regions, nor does it give when-not-to-use guidance. The 'Read-only.' line provides minor context but no alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's 'Read-only' line adds no new safety information. It does add that the tool 'returns each region and whether it is configured,' which gives some output context beyond the annotations. However, it does not disclose pagination, authentication requirements, or any other behavioral traits.

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

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

The description is three short sentences with no fluff: it states the action, read-only nature, and output content. The main purpose is front-loaded, and every sentence earns its place.

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

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

This is a simple list tool with good annotations and a well-documented query parameter. However, the 'skip_sku_check' parameter is completely unexplained, and with no output schema the return shape is only partially described. It is adequate for a simple read-only list, but not 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?

The tool description itself does not explain any parameters. The schema provides a thorough description for the 'query' parameter (JMESPath filtering, snake_case warning, examples), but 'skip_sku_check' has no description in the schema and no mention in the tool description. With schema description coverage at 50%, the tool description fails to compensate for the undocumented parameter.

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

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

The description uses a specific verb and resource: 'List the Zscaler Cellular regions available/configured for the customer.' It also clarifies the output ('Returns each region and whether it is configured'), which helps distinguish it from sibling tools like zcell_list_region_operational_status. However, the phrasing 'available/configured' is slightly ambiguous and no explicit sibling differentiation is provided.

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

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

The description implies this tool is for retrieving a customer's Zscaler Cellular regions and their configuration state, but it does not state when to use it versus alternatives, nor does it mention any exclusions. The read-only note provides some context, but there is no explicit 'use this over X when...' guidance.

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

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

Annotations already declare readOnlyHint: true, so the read-only nature is covered. The description adds a redundant 'Read-only.' statement and explains the output fields (ICCIDs, IMSIs, tags). It does not disclose other behavioral traits such as pagination, rate limits, or result ordering. Given the annotations cover safety, the description adds some context but not significant behavioral transparency beyond what annotations already provide.

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 long, front-loaded with the primary purpose, and each sentence earns its place. It avoids redundancy and fluff, covering purpose, read-only nature, output contents, and optional filtering in a compact format.

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 provides a high-level summary of the returned data (ICCIDs, IMSIs, tags) which is sufficient for an agent to understand the tool's output. It also mentions optional scoping. However, it does not address potential pagination, result limits, or any performance implications, which might be expected for a list operation. Given the tool's simplicity and annotations, this is reasonably complete but not exhaustive.

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 description adds meaning for the icc_ids parameter by stating 'Optionally scope to specific ICCIDs', which is not explained in the schema (only schema coverage is 50% for the query parameter). The query parameter has a detailed schema description, but the tool description does not mention it. Overall, the description enhances understanding of icc_ids, though it doesn't provide details on the format or usage of query beyond what the schema already offers.

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 'List Zscaler Cellular SIM map points' with a parenthetical clarifying it's a dashboard lat/lng summary. It specifies the resource (SIM map points) and the verb (List), and distinguishes it from sibling tools like zcell_list_sims (general SIM list) and zcell_list_sim_analytics_summary (summary variant) by focusing on map point data with lat/lng context.

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 provides context about what data backs the fleet map, implying use cases for map visualization, and mentions optional scoping to specific ICCIDs. However, it does not explicitly state when to use this tool versus alternatives like zcell_list_sim_analytics_summary or zcell_list_sims, nor does it provide any exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, and the description redundantly states 'Read-only.' It does add that the tool returns a 'SIM-count breakdown for the tenant,' which clarifies the output scope, but it does not disclose any other behavioral traits such as response format, pagination, or performance characteristics. Since annotations already cover the read-only nature, the description adds limited extra 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 description is two concise sentences: the first states the purpose, the second clarifies read-only status and return type. There is no unnecessary verbosity or repetition, making it efficient and front-loaded.

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

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

The tool is simple—a summary list with an optional query parameter. The description states the exact counts provided (total/used/active/inactive) and that it applies to the tenant. The query parameter is thoroughly documented in the schema. Given the tool's simplicity and schema coverage, the description is 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?

The description does not mention the optional 'query' parameter, but the schema provides a detailed explanation of its JMESPath usage, including examples and a warning about field names. With 100% schema description coverage, baseline is 3, and the description does not need to add further parameter semantics.

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

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

The description clearly states the action: 'List the Zscaler Cellular SIM status summary' and specifies the contents: 'total/used/active/inactive.' It is specific about the resource (SIM status summary) and the scope (for the tenant), distinguishing it from other list tools like zcell_list_sim_usage_by_sim.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, alternative tools, or conditions. It simply states what it does, leaving the agent without context on when it is the appropriate choice among the many sibling list 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds the output content (id, name, tracked ICCIDs) and the relationship to a sibling tool, which is useful context beyond the annotations. However, it does not disclose pagination behavior or any other side effects, and the read-only statement is redundant with the annotation. It adds some value but not extensive 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?

The description is two sentences, front-loaded with the purpose, and every sentence adds value. No redundant or vague wording. It is a model of concise, effective tool documentation.

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 is a simple list operation, the description provides essential context: what it lists, the output fields, and how to get deeper details. It does not describe pagination, but that is captured in the schema. With no output schema, it partially describes the return format, which is sufficient for a list tool. It could mention the `query` parameter or filtering options, but the schema covers that.

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 description does not explain any of the four parameters (name, page, size, query) other than indirectly referencing 'tracked ICCIDs'. Schema description coverage is only 25% (only query has a description), so the description must compensate, but it does not. There is no guidance on parameter semantics, making it hard for an agent to use filters or pagination correctly.

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 the verb ('List') and resource ('Zscaler Cellular SIM location groups'), and specifies the output structure ('Returns one row per group (id, name, tracked ICCIDs)'). It also distinguishes from sibling tools by directing to `zcell_get_sim_location_group` for detail, making the purpose unambiguous.

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

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

The description provides a clear context of use: listing groups, and explicitly tells when to use the sibling tool for detail ('Use the returned `id` with `zcell_get_sim_location_group` for the geo-fence and linked-policy detail'). It does not list exclusions or alternative usage scenarios, but the guidance is sufficient to differentiate this tool from its immediate sibling.

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 description reinforces the readOnlyHint annotation ('Read-only (browses the inventory)') and adds concrete behavioral context: it returns a page of curated SIM records plus an aggregate usage/pagination envelope. No contradictions are present; it could add authentication or rate-limit caveats, but the annotation already covers the safety profile.

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 3-4 sentences with no filler; the first sentence states the action, the second clarifies read-only behavior and return shape, and the third lists filter categories. It packs substantial guidance into a compact space.

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

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

For a 15-parameter list tool without an output schema, the description covers the core semantics: purpose, read-only nature, return envelope, and filter categories. It omits pagination defaults and exact filter syntax, but the presence of a detailed query-param description and the broad filter list make it mostly 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?

With only 7% schema description coverage, the description partially compensates by grouping filterable fields (ICCID, status, network status, country, tag, device attributes, IMEI lock status). It doesn't map these to exact parameter names or define value formats, and pagination parameters are only implied, not explained.

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 ('Search') tied to a concrete resource ('the Zscaler Cellular SIM inventory'), and clarifies it supports filters and pagination. This clearly differentiates it from sibling list tools like zcell_list_sim_usage_by_sim, which target usage rather than inventory.

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 establishes clear context as a read-only inventory browser and lists the available filter dimensions, making it easy to know when this tool fits. However, it never explicitly names alternatives (e.g., zcell_get_sim_details) or says when not to use it, so it misses the exclusion part.

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 description adds useful behavioral context beyond the readOnlyHint annotation: it specifies a 'days lookback window' and that it returns 'top countries'. This clarifies the impact of the `days` and `limit` parameters. No contradictions with annotations exist; the 'Read-only' statement aligns with readOnlyHint. It does not disclose details like sort order or exact return fields, but it is sufficiently transparent for a read-only list tool.

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

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

The description is two sentences, front-loaded with the main action, and contains no redundant or filler content. Every sentence earns its place, making it efficient and easy to parse.

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 no output schema, the description covers the core behavior: what is returned (top countries), the time window parameter, and the read-only nature. It could mention whether results are sorted by usage descending or what fields each record contains, but these are minor gaps. Overall, it is complete enough for an agent to understand and invoke the 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?

With only 33% schema description coverage, the description compensates by explaining that `days` controls the lookback window and that the result is 'top countries', implying `limit` controls how many countries are returned. The `query` parameter is already fully described in the schema. Thus the description adds semantic meaning to the otherwise under-described 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 starts with 'List Zscaler Cellular data usage grouped by country', which clearly states the verb (list), resource (Zscaler Cellular data usage), and grouping (by country). The parenthetical '(top countries)' further clarifies the output scope. This distinguishes it from sibling tools like zcell_list_sim_usage_by_sim and zcell_list_sim_usage_by_day, which group by different dimensions.

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 provides clear context: it returns the top countries by data usage over a days lookback window, implying when to use it (country-level aggregation). However, it does not explicitly contrast with alternatives such as by-SIM or by-day tools, nor does it state exclusions. The grouping information alone makes the intended use evident, but explicit when-not-to-use guidance is missing.

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

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

The readOnlyHint annotation already declares safety, and openWorldHint is false. The description adds useful behavioral context beyond annotations: one usage bucket per day, a lookback window, and optional ICCID filtering. It does not cover rate limits or exact output fields, but those are less critical for a read-only listing 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?

The description is short and front-loaded with the core behavior. There is minor redundancy ('per day' appears twice, and 'Read-only' duplicates the annotation), but overall it is efficient and structured well.

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, optional-query listing tool with no output schema, this description provides enough to understand the tool's purpose and return structure. It lacks explicit output-field details or timezone semantics, but the daily-bucket statement and schema's query guidance make it 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?

Schema description coverage is low (33%), but the description compensates for the key parameters: 'days' is explained as the lookback window and 'icc_id' as optional single-ICCID scoping. The 'query' parameter already has a thorough JMESPath explanation in the schema.

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

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

The description uses a specific verb ('List') with a clear resource ('Zscaler Cellular data usage per day') and indicates granularity and scope. This distinguishes it from sibling tools like zcell_list_sim_usage_by_sim and zcell_list_sim_usage_by_country.

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 clearly states the invocation context: daily usage over a lookback window, optionally scoped by ICCID. It does not explicitly name alternatives or when-not-to-use cases, but the 'per day' phrasing provides enough differentiation.

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