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

Discloses matching precedence (exact ID first, then exact name/serial/hw_id case-insensitive, then substring), never auto-picks multiple hits, includes site_id when available, and explains pagination semantics. This goes well beyond the readOnly/idempotent hints provided in 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 well-structured with a lead sentence and focused sections, but the Args block repeats parameter descriptions already present in the schema. This is slightly redundant but not excessive given the tool's complexity.

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 fully covers usage behavior, ambiguity handling, pagination, and return context (site_id). With output schema available and strong annotations, the description is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, and the description's Args section essentially mirrors the schema's parameter descriptions verbatim. It adds no new parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Resolve an ION/element name or exact ID without guessing.' It clearly distinguishes this tool from siblings like find_site or find_resource by focusing on element resolution and ID matching behavior.

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 clear procedural guidance: omit cursor on first call, use limit to page, and re-call with a more specific value or exact ID when ambiguous. It doesn't explicitly name alternative tools, but the intended usage 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?

Even with annotations (readOnlyHint, idempotentHint, destructiveHint) already establishing a safe read-only profile, the description adds valuable behavioral detail: it never silently picks a match when multiple records exist, details exact resolution order, explains ambiguity handling, and describes pagination semantics with next_cursor. This goes well beyond annotation hints and fully discloses the tool's search behavior.

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

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

The description is front-loaded with purpose, then organized into a clear 'Args' list, with each parameter explained in a tight sentence. No fluff or repetition beyond what is necessary for context. At ~150 words for a 4-parameter tool with complex matching semantics, it is appropriately sized and well-stuctured.

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 all key aspects of the tool: supported object types, matching rules, ambiguity behavior, pagination (cursor, limit, defaults), and explicit alternatives for uncovered object types. Given the output schema exists, return-value details are not required. For a search/resolution tool of this complexity, the description is complete and self-sufficient.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters thoroughly. The description's param details largely mirror the schema text (e.g., 'Exact ID match wins first, then exact name...' and 'Opaque pagination token'). Thus it adds no new meaning beyond the schema; it simply repeats it in prose, meeting the baseline of 3 but not exceeding it.

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

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

The description opens with a specific verb and resource: 'Resolve common Prisma SD-WAN objects by human name or exact ID.' It then enumerates the exact object families covered and explicitly distinguishes itself from sibling tools (find_site/find_element) by stating they are for sites/ION elements while this tool is not. This fully clarifies purpose and differentiation.

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 explicit usage context: which object types to use it for, and a direct exclusion: 'Use find_site/find_element instead for sites or ION elements — this tool does not cover those.' It also describes the prioritization logic for name matching (exact ID, exact name, substring) and warns about ambiguity, giving the agent clear behavioral guidance for when to call and what to expect.

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 read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: exact matching precedence, case-insensitivity, substring fallback, no auto-picking of ambiguous results, and cursor-based pagination. This goes well beyond the structured 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 well-structured with a clear opening sentence and an organized Args section. It is slightly verbose, but every detail about matching precedence and pagination earns its place, and it is front-loaded with the core purpose.

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 presence of an output schema, the description correctly focuses on non-obvious behaviors: ambiguity handling, matching precedence, and pagination. It fully covers the tool's complexity with no missing critical context.

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

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

Schema description coverage is 100%, and the description essentially repeats the same parameter details found in the schema (name, cursor, limit). It adds no new semantic meaning beyond what is already structured, so the baseline 3 applies.

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

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

The description uses a specific verb "Resolve" with a clear resource (site) and explicitly states the tool returns matching candidates without guessing. It distinguishes itself from sibling tools like find_element and find_resource by focusing on site name/ID resolution.

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 (to resolve a site name or exact ID) and gives explicit follow-up guidance for ambiguous matches: check the 'ambiguous' flag and call again with a more specific name or exact id. It does not explicitly name alternatives, 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description adds critical context: it never writes to disk, never calls the API, silently drops unknown element keys, and site_id is free text not resolved against the live tenant. 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?

The description is well-structured: a front-loaded summary, then key side-effect disclosures, then concise parameter details. Every sentence adds informational value, with no fluff or redundancy.

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

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

The description covers return format (structured object + YAML), side effects (none), validation target, and caller responsibilities. It omits explicit error-handling behavior on validation failure, but the presence of an output schema and rich annotations reduces the need for further detail.

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

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

Schema description coverage is 100%, and the description largely restates the schema's parameter descriptions. It adds no new formatting/syntax nuances beyond what the schema already provides, though the silent-drop behavior is useful context but also present in the schema.

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

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

The description states a specific verb ('Build and validate') and resource ('one site's Prisma SD-WAN config fragment'), clearly distinguishing it from the sibling read-only/query tools. It also describes the output (structured object + YAML) and the validation target.

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 tool is for offline config generation used by downstream automation (e.g., Ansible) and explicitly states it never writes to disk or calls the Prisma SASE API, leaving application to the caller. This clearly implies when to use it versus live-network tools, though it doesn't explicitly name 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, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context such as pagination via cursor/limit and operation-specific parameter requirements. It does not contradict annotations, and the added details are valuable.

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 well-structured: a one-line summary followed by a concise Arg list with each parameter explained in a compact format. The most important context is front-loaded, and every sentence provides necessary 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 fully covers all operation variants, required vs optional parameters, pagination behavior, and resolution semantics. Since an output schema exists, the lack of return-value details is acceptable. The tool is complex with 6 parameters and 5 operation modes, yet the description handles it comprehensively.

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 83%, and the description largely repeats the property descriptions already present in the schema. For instance, the 'operation' and 'element' descriptions are nearly identical. No new semantic meaning is added, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Inspect cellular modules, firmware status, APN profiles, and module images,' which is a specific verb and resource. It clearly differentiates this tool from sibling tools like get_interfaces or get_wan by focusing on cellular-specific data.

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

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

The Args section explicitly explains which operations require no parameters, which require 'machine', and which require 'element', providing clear usage context. However, it does not mention alternatives or exclusions relative to sibling tools, so it falls 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 indicate a safe, read-only, idempotent operation, but the description adds significant behavioral nuance: it explains that missing site info leads to an error 'rather than guessing', that `port_to_vlan`/`vlan_to_port` on non-switch models yield a 'does not support switch configuration' message (indicating wrong device type, not a failed lookup), and advises against retrying. It also documents pagination cursor semantics. This goes well beyond the annotation basics.

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 well-structured: a one-line summary followed by a clear list of parameters with inline explanations. It is somewhat lengthy, but every sentence conveys necessary behavioral or dependency details. It earns a high score for being appropriately front-loaded and free of fluff, though a more compact presentation could slightly improve it.

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

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

Given the tool's complexity (multiple operations with different requirements, pagination, site inference), the description is remarkably complete. It explains operation-specific prerequisites, error semantics, and pagination behavior. An output schema exists, so not detailing return values is acceptable. The description leaves no obvious gaps for an agent to misuse the tool.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions for `element`, `site`, `cursor`, `limit`, and `operation`. The tool description's Args section largely mirrors the schema descriptions, adding no additional meaning beyond what the schema already conveys. Therefore the schema does the heavy lifting, and the description adds no new parameter-level insight.

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 ('Retrieve') and a clear resource ('common device-side diagnostic state'), followed by a concrete list of diagnostics (LLDP neighbors, MAC table, port/VLAN mappings, BFD peers, application-probe configuration). This clearly differentiates it from sibling tools like get_routing or get_interfaces by focusing on device diagnostics rather than routing or interface data.

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

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

The description provides clear operation-level guidance: which operations require only `element`, which require a resolvable `site`, and which require switch-capable models. It also explains the error behavior for unsupported device types. However, it does not explicitly contrast this tool with alternatives (e.g., 'use get_routing for routing state'), so it falls 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?

The description adds significant behavioral context beyond the readOnly/idempotent annotations: element resolution accepts multiple identifier types, ambiguous names fail instead of guessing, software failures are reported under partial_errors, and interface fan-out is bounded by interface_limit. These are not visible in the annotations.

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

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

The description is front-loaded with a clear one-sentence purpose, but the subsequent Args block is a verbatim duplicate of the input schema's parameter descriptions. This redundancy makes it longer than necessary, though the structure is logical.

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 an output schema and annotations, so the description needn't cover return values or safety. The description fully covers the resolution logic, optional invocation parameters, and error-handling behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, and the Args block in the description essentially mirrors the schema's parameter descriptions. The description adds no new meaning beyond the schema, though it does restate the resolution and partial_errors nuances already present 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 begins with 'Return a combined health view for one ION element,' a specific verb+resource statement. It clearly distinguishes from sibling get_* tools by emphasizing 'combined' and 'health view,' and the Args detail the optional software and interface fan-out.

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 implies when to use this tool: when a combined health view is needed, with optional software and interface status. It provides context about the interface fan-out being off by default due to cost, but it does not explicitly name alternatives or exclusions like 'use get_interfaces for raw interface stats.'

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses key behaviors: session/token fields are always redacted, non-existent object_id returns an empty list rather than an error, and pagination uses an opaque cursor. These are significant behavioral details that an agent needs to interpret results correctly.

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 somewhat long but well-organized with an Args section. The core purpose is front-loaded, and each parameter explanation carries necessary detail. It could be tightened, but the structure makes it scannable. No unnecessary 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 5 parameters, 8 enum values, and an output schema, the description covers most operational aspects: redaction, pagination, parameter dependencies, and error semantics. The only clear miss is the 'detail' parameter, which is not mentioned. Overall, it provides sufficient 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?

Schema coverage is 80%, so the baseline is 3. The description adds valuable nuances for object_id (the empty-list behavior for non-existent IDs) and operation (which operations require object_id), plus pagination semantics for cursor and limit. However, it omits the 'detail' parameter entirely, which appears in the schema with no explanation, leaving a 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 opens with 'Inspect directory/tenant identity state,' specifying a clear verb and resource. It then enumerates the distinct operations (directory_service, tenant_users, element_user_access, etc.), which distinguishes it from sibling tools like get_inventory or get_routing. The redaction note adds further specificity.

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 tool's scope ('directory/tenant identity state') and lists the available operation types, implying when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusion 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses substantial behavioral traits: fan-out up to a ceiling of 100, inline failure handling, ambiguous substring returning all candidates, pagination via cursor, and exact limit semantics. This goes far beyond what annotations 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 well-structured with a one-sentence summary, a behavioral note, and clear parameter bullets. Despite its length, every sentence adds value and the structure aids comprehension.

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 remarkably complete for a complex tool: it covers edge cases, pagination, limits, failure behavior, and mode-specific semantics. An output schema exists, so not detailing return structure is acceptable.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds extra context such as the fan-out ceiling and the interaction between interface omission and status mode, so it earns a 4.

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

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

The description opens with a specific verb and resource: 'Retrieve interface configuration and/or operational state for one element.' This clearly distinguishes it from sibling tools like get_routing or get_wan, and the detail about enumerating interfaces and fanning out adds further specificity.

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 explains when to use the tool (for interface configuration/state) and describes the modes including when extra API calls occur. It does not explicitly name alternatives or provide when-not-to-use instructions, so it falls 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 destructiveHint=false, but the description adds significant behavioral detail: summary vs full mode, pagination tokens, redacted controller records, and the special aggregate summary for applications without search. These are meaningful operational nuances beyond the structured fields.

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 well-structured with an introductory sentence followed by a clear Args list. It is somewhat long but every sentence conveys relevant information, with no fluff or redundancy beyond the unavoidable repetition of schema details.

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 complexity (5 params, multiple modes, large collections), the description covers all key operational aspects: pagination, output modes, collection-specific behavior, and alternatives. An output schema exists, so detailed return values are not needed in 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?

The schema description coverage is 100% and the tool description's Args section essentially duplicates the schema parameter descriptions. No additional meaning is provided beyond what the schema already contains, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Retrieve core Prisma SD-WAN inventory.' It also distinguishes itself from sibling tools by noting 'Use find_site/find_element/find_resource instead if you already know a name and just need to resolve it to an ID.' This clearly frames the tool's scope as broad inventory retrieval rather than targeted name-based lookups.

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?

Explicit guidance is given on when to use alternatives: 'Use find_site/find_element/find_resource instead if you already know a name...' Additionally, it advises using search/limit for large collections and notes the aggregate behavior for applications, giving clear situational context.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds practical behavioral context beyond annotations: pagination is cursor-based, first call omits cursor, limit defaults to 50 with max 200, and local_prefixes behaves differently based on site presence. This is useful but doesn't cover every edge case like error handling or rate limits.

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

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

The description is well-organized: a one-line purpose followed by a structured Args list. It is concise without redundancy, and each sentence adds value (operation modes, param requirements, pagination defaults). Minor repetition between description text and schema descriptions is acceptable given the need for self-contained tool docs.

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 and an output schema, but the description is complete enough on its own: it explains every operation's parameter requirements, pagination behavior, and the effect of site on local_prefixes. Since an output schema exists, return-value documentation is not needed. The context provided fully covers the tool's usage surface.

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

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

Schema description coverage is 100%, with every parameter described in the input schema. The description's Args section largely duplicates those schema descriptions (operation, site, element, cursor, limit) without adding new meaning. While it groups operations and their requirements clearly, that information is already in the operation enum description. Baseline 3 is appropriate.

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

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

The description opens with a clear, specific verb 'Inspect' and names the resource 'IPFIX/flow-export configuration' along with its subcomponents (collectors, filters, templates, prefixes). This distinguishes it from sibling tools like get_routing or get_interfaces, which focus on different network domains.

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 detailed operation-specific usage instructions, explaining which parameters are required or optional for each operation (e.g., 'config' requires site + element, 'local_prefixes' takes optional site). It references find_site and find_element for resolution, but does not explicitly compare against alternative tools or state when not to use this tool, so it falls 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?

The description adds substantial behavioral caveats beyond the annotations: unwindowed events/alarms can silently miss older incidents, link/probe metrics are recorded telemetry not active probes, raw flows are capped at 500, and link_metrics responses may be replaced by a warning stub. These are critical operational truths essential for correct interpretation.

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 long, but the tool is complex with 13 parameters and 12 operation types. It is well-structured with a front-loaded summary, a prominent early warning, and organized Args; however, it repeats much of the schema parameter documentation, keeping it from a perfect conciseness score.

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 this complexity, the description covers all essential operational constraints: parameter scopes, ignored-parameter rules, required pairings (start_time/end_time), pagination, response-budget failures, and dataset-specific behavior. The presence of an output schema further covers return shapes, so no major gaps remain.

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

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

Schema description coverage is 100% and the schema already contains equally detailed parameter explanations for operation, site, start_time, end_time, limit, and raw. The description's Args section largely duplicates these descriptions, so it adds no significant meaning beyond the schema, meeting the baseline but not exceeding it.

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

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

First sentence clearly defines the tool as 'Unified operational monitoring for incidents, flows, metrics, and AIOps,' which names the resource and scope and distinguishes it from sibling get_* tools that target specific domains. The detailed operation enumeration reinforces the unified monitoring purpose.

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

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

The description does not name sibling tools or provide explicit when-to-use versus get_routing/get_topology, but the 'Unified operational monitoring' framing plus operation-specific requirements (e.g., site required for flows/link_metrics/probe_metrics, events/alarms need start_time/end_time for thorough incident analysis) give clear application context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and safe behavior, so the bar is lower. The description adds useful context about pagination and operation-specific parameter dependencies, which reinforces the tool's read-only nature without contradicting annotations. It doesn't disclose any additional side effects or limitations beyond what schema/annotations imply.

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 well-structured with a clear purpose sentence and a compact parameter list. It is a bit verbose due to repeating schema descriptions, but the operation-grouping summary at the top justifies the length. Every sentence serves a purpose, though some redundancy with schema exists.

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 presence of an output schema and read-only annotations, the description is complete. It explains pagination (cursor, limit), required vs optional arguments per operation, and tenant-wide vs filtered scopes. No critical information is missing for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, and the parameter descriptions in the tool description mostly duplicate schema text. However, the description adds a valuable summary grouping operations by required parameters (e.g., 'Requires site + element: config, dynamic_rps...'), making the dependency structure explicit and easier to parse than the raw schema.

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

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

The description opens with a clear, specific verb ('Inspect') and enumerates exact resource categories (multicast config, RPs, peer groups, routes, IGMP, WAN status). This distinguishes it well from sibling tools like get_routing or get_wan, even though it doesn't explicitly name them.

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

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

The description gives precise per-operation parameter requirements, which helps the agent understand internal usage constraints. However, it doesn't explicitly state when to choose this tool over siblings, mention alternatives, or provide exclusion criteria. The guidance is implicit 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, idempotentHint, and destructiveHint false, but the description adds valuable behavioral context: site/element names resolve to controller IDs, ambiguous names return an error instead of guessing, ntp_status auto-selects an NTP config if exactly one exists and lists candidate IDs if more, and pagination uses an opaque cursor with a page size default of 50 and max of 200.

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 opens with a one-line summary, then uses an 'Args' list to detail each parameter. Although it is long (~250 words), every sentence carries operational necessity: operation groupings, resolution behavior, edge-case handling, and pagination. No waste.

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 complexity (6 parameters, 13 operation enums, variable required-parameter combinations), the description is exhaustive: it covers resolution semantics, per-operation requirements, ntp_status fallback and failure behavior, pagination, and page size limits. An output schema exists, so return-value details are not needed.

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

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

Schema coverage is 100% — every parameter has a description, including the operation enum values grouped by required inputs. The description essentially repeats the schema's parameter descriptions (e.g., site resolution, object_id behavior) without adding new semantic meaning, so it meets the baseline but does not exceed it.

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

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

The description states 'Inspect DNS, DHCP, NTP, syslog, SNMP, TACACS+, and RADIUS read-only state' — a specific verb ('Inspect') paired with an explicit enumerated resource set. This clearly differentiates the tool from siblings like get_routing, get_wan, and get_interfaces by naming the exact service scope.

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 per-operation guidance: 'No params required: dns_profiles...' and lists which operations require site, element, or both. It does not explicitly mention alternatives like 'for routing use get_routing', but the tool is self-contained and the parameter requirements effectively tell the agent when to use this tool and how to select among its 13 operations.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals a recursive redaction of sensitive values and the specific 400-rejection behavior for the `folder` parameter. It also documents pagination semantics (cursor/limit), giving the agent expectations for server behavior that are not derivable from the schema 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 front-loaded with a one-sentence purpose and a clear 'Args:' list. However, the parameter explanations repeat the schema descriptions nearly verbatim, adding length. The structure is good but the redundancy prevents a perfect score.

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 an output schema present, the description covers operation modes, parameter requirements, pagination, and error behavior. The only notable gap is the unexplained `detail` parameter, and the interplay between `reports` and the (rejected) `folder` is clarified. Overall, this is strong for a multi-mode tool.

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

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

The schema already describes most parameters (83% coverage) with detailed explanations, and the description largely duplicates those descriptions. It adds no substantive new meaning for parameters beyond the schema, though the redaction note is globally relevant. The `detail` parameter is left unexplained in both description and schema.

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

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

The description opens with a clear verb ('Inspect') and enumerates the resource categories ('tenant/platform metadata, licenses, SKUs, machines, and reports'), distinguishing it from sibling tools focused on network or device-specific reads. The operation parameter further enumerates 10 distinct read modes, making the tool's scope concrete.

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 identifies which operations require the `machine` parameter, states that `reports` takes no parameters, and explicitly warns that `folder` is rejected. It references `find_resource` for machine resolution, providing a cross-tool cue, but it does not explicitly state when to prefer this tool over sibling tools (e.g., `get_software` vs `machine_software`).

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses important behaviors: ambiguous policy names are never auto-selected, errors list candidates, and security policy-set status is reported as unsupported rather than invented. This adds meaningful transparency about edge cases and error handling.

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 well-structured with a summary paragraph and a detailed Args section, making it easy to scan. It is longer than necessary because the Args section duplicates schema descriptions, but every part contributes useful context. The formatting with backticks and line breaks enhances readability.

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

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

Given the tool's complexity (5 parameters, multiple operations, cross-parameter constraints), the description is exceptionally complete. It covers all operations, parameter relationships, default behavior, pagination, and unsupported cases. The presence of an output schema further reduces the burden, and the description fills the remaining gaps.

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

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

The schema descriptions already cover 100% of parameters, so the baseline is 3. The description's first paragraph adds relational context not fully captured in schema, such as the dependency of rules/status on policy and the limitation of 'all'. However, the Args section largely restates schema descriptions, so the added semantic value is moderate, not exceptional.

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 clear, specific action: 'Inspect the major Prisma SD-WAN policy families using human policy names.' This distinctly identifies the resource (policy families) and the verb (inspect), and it differentiates the tool from sibling get_* utilities by focusing on policy families and their operations.

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

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

Usage guidance is strong: it explains when to use each operation (sets/stacks tenant-wide, rules/status require policy), and explicitly notes that family='all' only supports sets/stacks and that security status is unsupported. However, it does not explicitly name alternative sibling tools for the unsupported cases, so it falls 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds pagination behavior (cursor/limit) and notes that object_id is ignored for non-status operations, but these details are also present in the schema. No extra behavioral context such as auth or rate limits is provided, but there is 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?

The description is front-loaded with a clear purpose, followed by a structured Args list that methodically covers six parameters. Despite its length, every sentence earns its place given the tool's 10 operation variants and dependent parameters. No redundant or vague phrasing.

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 complexity (10 operations, 6 parameters, interdependencies), the description fully covers parameter requirements, pagination, and operation variants. An output schema is present, so return-value documentation isn't needed. The description is complete for understanding this tool's behavior, even though sibling differentiation is handled elsewhere.

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

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

Schema description coverage is 100%, and the description's Args section largely mirrors the schema's property descriptions. It adds minimal new meaning beyond organizing the operation-dependent requirements, which is already in the schema. Thus, the baseline 3 is appropriate.

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

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

The description opens with 'Inspect Prisma Access/SASE integration, connections, prefixes, and ADEM state,' which is a specific verb ('Inspect') tied to a concrete resource domain. This clearly distinguishes it from sibling tools like get_routing or get_inventory, which target different resources. The operation enum further specifies the exact reads supported.

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 which operation requires which parameters and mentions that some operations need no params, giving clear usage context. However, it does not explicitly state when to use this tool instead of siblings or when to prefer an alternative, so it stops 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 read-only, open-world, and idempotent behavior. The description goes far beyond this by documenting resolution order (exact ID, then name/IP, then substring), structured error behavior with candidates, fan-out logic for OSPF neighbors/prefixes, and the extra API call per peer for include_prefixes with its fan-out limit. 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 front-loaded with a clear summary, then systematically covers all eight parameters and their interactions. Despite its length, every sentence serves a purpose—explaining operation-specific rules, defaults, and error handling. The structured Args block is easy to scan and free of 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?

Given the tool's complexity (12 operations, 8 parameters, multiple edge cases), the description is exceptionally complete. It covers all operations, parameter combinations, error behavior, pagination, server limits, and default values. The presence of an output schema eliminates the need to describe return formats, allowing the description to focus on invocation and behavior.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds meaningful semantics above the schema: resolution rules for element and peer, ignored-parameter behavior per operation, the meaning of prefix_kind values, and the implication of include_prefixes with its performance tradeoff. This enriches an already well-described schema.

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

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

The description opens with a specific verb and resource: 'Inspect BGP, OSPF, static routes, and routing policy objects for one ION.' This clearly distinguishes the tool from sibling tools like get_interfaces or get_topology by focusing exclusively on routing-related data for a single element.

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 detailed operational guidance, such as when to use include_prefixes ('Leave false for a quick status check') and which parameters are required for specific operations. It doesn't explicitly name alternative tools, but it clearly defines the scope of this tool and gives nuanced advice for its suboperations.

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 important behavioral details beyond the annotations: client-side catalog search, automatic name resolution for site/element, pagination token semantics, and that zero matches still return the same collection key with an empty list. These disclosures go well beyond the readOnlyHint and idempotentHint annotations, giving the agent a clear model of the tool's runtime behavior.

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

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

The description is well-structured with a brief overview followed by a labeled Args list. Each sentence earns its place, providing necessary detail without fluff. The length is justified by the tool's complexity, and the format makes it easy to scan.

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 6 parameters, a 10-value enum, and an output schema, all of which require substantial context. The description covers operation-specific arg requirements, special behavior for SD-WAN app IDs, pagination, and response shape notes. Combined with the rich schema and annotations, the description fully equips an agent to 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?

The schema description coverage is 100%, so the schema already fully documents each parameter. The description essentially repeats the schema text without adding extra nuance (e.g., no format details beyond what's in the schema). Per calibration, baseline 3 is appropriate when the schema carries the load.

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 the specific verb 'Inspect' and identifies the exact resources: security zones, application catalog/version, prefixes, and SD-WAN apps. This clearly distinguishes it from sibling tools like get_routing or get_wan by enumerating the unique resource categories.

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 detailed per-operation usage guidelines, such as which arguments are required or ignored for each operation (e.g., 'site_zones requires site, element_zones requires site and element'). It does not explicitly mention alternative tools, but the resource scope is clear enough that an agent can infer when to use this tool; the lack of explicit exclusions or sibling comparisons prevents 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, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds meaningful behavioral details such as pagination semantics ('cursor', 'limit', default page size 50, max 200) and the resolution behavior of site/element ('resolved the same way as find_site'). This exceeds the annotation baseline.

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 yet complete, structured as a docstring with a clear summary and an Args section. Each sentence earns its place, particularly the explanation of operation-specific requirements and pagination. It is appropriately sized for a tool with multiple read modes.

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 6 parameters and 8 distinct operations, the description provides thorough guidance on operation selection, parameter requirements, and pagination. The main omission is the 'detail' parameter, which remains undocumented in both the description and schema. With an output schema present, return values are covered, so the description is largely 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 schema already provides descriptions for 5 of 6 parameters (83% coverage), meeting the high-coverage baseline. The description further adds value by explaining operation-specific parameter dependencies and listing the exact operation enum values. However, the 'detail' parameter is completely omitted from the description, which is a minor 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 'Inspect' and lists distinct resources: service connections, endpoints, binding maps, service labels, and extensions. This clearly differentiates the tool from siblings like get_routing or get_network_services, which focus on other aspects.

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 each operation, explicitly stating which parameters are required for certain operations (e.g., 'Requires site: site_connections, site_extensions'). It does not, however, explicitly mention alternatives or exclusion scenarios, but the operation enum itself acts as a selector, making usage 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 read-only, idempotent, and non-destructive hints. The description adds useful behavioral context about pagination (cursor/limit), operation-specific requirements, and element resolution. It doesn't add extra side-effect info but confirms the safe-read nature.

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 efficiently organized with a one-sentence overview followed by an Args list. Each parameter gets a brief, focused explanation. No unnecessary 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 multi-operation tool with 5 params and an output schema, the description covers the main use case, operation selection, pagination, and element resolution. The missing 'detail' parameter and lack of return-value explanation are minor gaps given the output schema exists.

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

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

Schema coverage is 80% (4 of 5 params described in schema). The description reiterates operation, element, cursor, and limit with similar wording, adding minor grouping context. The 'detail' parameter is not mentioned in the description, missing a chance to compensate for its absence 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 opening sentence clearly states the tool's purpose: 'Inspect element software state/status and tenant-wide upgrade/template status.' This uses a specific verb+resource and distinguishes from sibling tools like get_inventory or get_platform.

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 each operation, such as requiring 'element' for element_state/element_status and noting tenant-wide operations need no params. It also references find_element for resolution. However, it doesn't explicitly contrast with alternative tools, so it stops 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?

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description deeply discloses behavior: summary returns only non-up links, full requires filters to avoid flooding, basenet performs one API call per leg with a 100-leg fan-out cap, and 'node_count' can legitimately be 0 alongside non-zero link counts. It also highlights ID semantics (path_id vs anynet_link_id). This is rich, non-obvious behavioral context that annotations alone cannot convey.

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 long but every sentence carries necessary information for correct invocation. It is structured into a short purpose statement followed by itemized parameter explanations. Repetition of 'requires site' is intentional reinforcement of a critical constraint. The length is justified by the tool's complexity (seven parameters, multiple modes, pagination, ID semantics).

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

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

Given the tool's complexity and the presence of an output schema, the description covers all essential usage contexts: mode differences, filter requirements, pagination tokens, leg_offset mechanics, and how to interpret unusual return values like node_count=0. It also explains that basenet exposes element/interface-level underlay info. No critical behavioral aspect appears omitted for effective 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?

Although schema coverage is 100%, the description significantly enriches every parameter: it explains defaults, interdependencies (site required for full and basenet), edge cases (leg_offset resumption, node_count semantics), and pagination behavior. For instance, it clarifies that cursor is opaque and must be copied from next_cursor, and that limit has a server default of 50 with max 200. This far exceeds the schema's bare descriptors.

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 'Return AnyNet topology with careful ID semantics preserved', which is a specific verb+resource statement. It clearly distinguishes this from sibling tools like get_routing or get_wan by detailing topology-specific modes (summary/full) and views (anynet/basenet). The tool's purpose is unambiguous and well-scoped.

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 explicit guidance on when to use summary vs full mode, when basenet is appropriate, and states requirements (site required for full unless status is set, and for basenet). It also documents exclusions, such as refusing a tenant-wide full dump without filters. However, it does not explicitly compare this tool to sibling alternatives (e.g., when to prefer get_wan for underlay instead), so it stops short of a full 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, idempotentHint, and destructiveHint=false, and the description reinforces this with "read-only state." Beyond annotations, it discloses important behaviors: pagination via `cursor` and `limit` with server defaults, the rejection of `site` for `vpn_links`, and the semantic nuance that `object_id` must be the leg ID from a topology tool's basenet view, not the parent path ID. 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?

The description is long but well-organized, with a clear intro sentence and a structured Args block. Every sentence contributes useful information: operation semantics, parameter requirements, edge-case behaviors (e.g., vpn_links rejection of site), pagination rules, and defaults. The structure is front-loaded with the core purpose and efficiently categorizes operations by tenant-wide vs site-required, so the length is justified.

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 9 operations and 6 parameters, the description is remarkably complete. It covers all operation-specific constraints, explains when site/element/object_id are required or ignored, describes pagination and defaults, and references `get_topology` for additional context. Since an output schema exists, the description does not need to enumerate return values, and the presence of `next_cursor` in the description complements the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args section largely mirrors the schema descriptions, with only marginal additions like the general rule "Operations needing a site or element accept names or IDs" and the explicit note about `object_id` being from basenet. These add slight value, but the schema already conveys the same parameter meanings, so the description does not meaningfully go beyond it.

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

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

The description opens with a specific verb and resource: "Inspect WAN, VPN, VRF, LAN, and IPsec read-only state through one semantic tool." This clearly states the tool's function and scope, and the detailed operation list (networks, vrfs, ipsec_profiles, interfaces, paths, vpn_links, lan_networks, vpn_leg_status/state) distinguishes it from sibling tools like get_routing or get_interfaces by covering a distinct WAN-focused domain.

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 extensive usage context, including which operations require `site` or `element`, that `vpn_links` cannot be narrowed by site, and that `vpn_leg_status`/`vpn_leg_state` require `object_id`. It also points users to `get_topology` for matching legs to sites. However, it does not explicitly contrast with alternative sibling tools (e.g., when to use get_wan vs get_interfaces), so it stops short of full when-to-use/when-not-to-use 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 establish read-only and idempotent behavior. The description adds valuable context: 'Nothing is ever truncated at either step' and the parameter precedence rules for ignored arguments. This goes well beyond the structured 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 well-structured with a one-sentence summary, a usage workflow paragraph, and a detailed Args block. It is somewhat long and the Args section duplicates the schema, but the added precedence information and examples justify the length.

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 fully covers the discovery workflow, output expectations at each step, and edge cases (ignored parameters, large domain responses). With an output schema present, the description's level of detail is sufficient for a capable agent to 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?

Schema descriptions match the Args section, but the description adds examples (sites_devices, security_policies) and clarity about parameter interactions and ignored-argument precedence. It describes the effect of 'detail' on response size, which is not evident from the schema 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 opens with a specific verb+resource: 'Browse the v2 capability catalog when no semantic tool fits the request.' It explicitly names read_capability as its companion and explains the browse→select→read workflow, distinguishing it from semantic tools and read_capability.

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 provides explicit guidance: 'Normal operator workflows should prefer semantic tools' and positions this tool as a discovery fallback. It also explains when to call with no args, with domain, and with action_id, and notes that method is ignored when domain is omitted, and domain/method are ignored when action_id is 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, idempotentHint=true, and destructiveHint=false, but the description goes further: it discloses central recursive secret redaction, response-size limits, default blocking of unverified actions, and two specific traps (retrieved_fields being answered with fabricated values, and body-level limit truncating without a cursor). These are critical behavioral details beyond what annotations convey. 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?

The description is front-loaded with a one-sentence purpose, followed by usage guidance and then a structured Args section. Every sentence earns its place: it covers validation, redaction, the blocked-action env var, pagination, body traps, and detail modes. Although long, the tool is complex (6 parameters, multiple caveats), and the structure makes it easy to scan.

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 complexity (6 parameters, output schema, annotations), the description is complete: it explains purpose, when to use it, parameters, pagination, detail mode, validation, and the unverified-compat guardrail. The output schema handles return-value documentation, so the description need not repeat that. No notable gaps.

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

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

The input schema has 100% parameter description coverage, and the schema's descriptions exactly reuse the description's Args text. Therefore, the description adds no meaning beyond the schema for parameters. Baseline 3 applies because high schema coverage means the schema already carries the burden.

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: 'Execute one exact read-only registry capability as an expert escape hatch.' This clearly identifies the tool's function and distinguishes it from semantic sibling tools (get_*, find_*) by framing it as a low-level escape hatch. The phrase 'one exact read-only registry capability' also conveys precision and scope, 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 explicit usage guidance: 'Prefer the semantic tools first' and 'Use list_capabilities to discover an action_id.' It also warns about the MCP_ALLOW_UNVERIFIED_COMPAT environment variable and that unverified actions are blocked by default. This gives clear recommendations on when to use the tool versus alternatives and how to handle blocked actions.

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?

Beyond the readOnlyHint, the description discloses explicit error behavior: unresolved IDs are reported rather than guessed, and ambiguous site names return an error listing candidates. This adds valuable behavioral context about failure modes, which annotations do not cover.

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 compact and well-organized: a one-sentence purpose, a design note, and a clean Args block. Every sentence earns its place, and the structure makes the content easy to scan and understand.

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 moderate complexity, rich annotations, and output schema, the description covers purpose, parameter usage, error behavior, and typical source of the IDs. No critical context is missing; the output schema handles return-value documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter details almost verbatim in the Args section, adding no new meaning beyond what the schema already provides. It does not clarify types, formats, or edge cases beyond the schema definitions.

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

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

The description opens with a specific verb+resource: 'Resolve an opaque path ID to a WAN interface, AnyNet link, or VPN leg.' This clearly distinguishes it from sibling list/query tools like get_wan or get_routing by focusing on resolution of opaque IDs. It also notes the design principle of not guessing, which further clarifies the tool's unique role.

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 context by stating path IDs are 'typically copied from ... output of a routing/WAN tool such as get_wan or get_routing.' This tells the agent when to use resolve_path, but it does not explicitly mention when not to use alternatives or name sibling tools as fallbacks. The guidance is clear but lacks explicit 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 goes far beyond the annotations by disclosing that diagnostics send real packets, policy validation precedes address resolution, missing credentials fail before any connection, host-key checking is always strict, output is capped per command, and completion is determined by the device prompt. It fully explains the operational side effects and error behavior. No contradiction with annotations exists.

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 well-structured with clear sections for purpose, policy, call order, arguments, credentials, and output behavior. However, it is somewhat verbose and repeats parameter explanations already present in the schema, which reduces conciseness. Overall, the structure is logical and the detail is mostly warranted given the tool's complexity.

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 all critical operational aspects: policy enforcement, call order, credential handling, host-key verification, output capping, per-command status, and completion semantics. An output schema is present to explain return values, and the description adds context that cannot be inferred from schema or annotations. The tool is complex, and the description is fully sufficient for safe and correct usage.

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

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

Schema description coverage is 100%, and the parameter descriptions in the Args block largely duplicate the schema's own descriptions (e.g., `host` always wins, `element` is a label when `host` given). The description does add the batch rejection rule for `commands` and explains the `commands` parameter's policy dependency, but this is marginal added value. Thus the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Run a batch of policy-approved commands on one Prisma SD-WAN ION over SSH.' It clearly distinguishes itself from sibling get_* tools by focusing on command execution, and further scopes the purpose via the approved command families (`dump`, `inspect`, `ping`, `tcpping`, `dig`).

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 states which command families are allowed and that everything else is denied fail-closed, giving clear when-to-use and when-not-to-use guidance. It also explains the fixed call order and fail-closed behavior. However, it does not explicitly contrast with alternative tools or state 'use this for troubleshooting commands versus get_* for retrieving data', so it stops short of a complete alternatives comparison.

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