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

With no annotations, the description carries the behavioral burden well: it explains identity normalization, separate handling of service accounts, ranking of findings by unexpectedness, and that results are observations rather than verdicts. It does not cover permissions, performance limits, or output shape in detail, but the key interpretive behavior is disclosed.

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 dense but mostly front-loaded, starting with the identity-centric view and then explaining differentiation, identity resolution, service-account handling, and ranking caveats. Each sentence contributes useful context, though it is longer than strictly necessary for a well-described schema.

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

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

For a complex ten-parameter analysis tool with no output schema and no annotations, the description provides the conceptual model an agent needs: what is analyzed, how identities are normalized, how service accounts are treated, and how findings are ranked. It lacks explicit output structure details, but the schema covers parameter mechanics and the description covers interpretation.

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

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

Schema description coverage is 100%, so all ten parameters are already documented. The description reinforces the identity-resolution and service-account concepts that matter for interpretation, but adds little parameter-specific syntax or constraints beyond what the schema provides.

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

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

The description clearly establishes an identity-centric traffic view and enumerates what it reports: account, workloads, destinations, and time period. It distinguishes itself from workload-label-based views, but does not explicitly name a sibling tool or use a direct verb phrase such as 'builds an identity graph.'

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

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

It gives clear usage context: answering least-privilege questions about what an account can reach and from how many places, especially where workload labels fall short. It does not provide explicit exclusions or point to named alternative tools for overlapping traffic-analysis tasks.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the return fields (status, health_http_status, health_round_trip_ms, total_seconds), what error messages contain (host, wait duration, HTTP status/timeout), how to interpret failures (5xx = PCE/front end, timeout = network), and that waits are bounded by MCP_PCE_RETRIES and MCP_PCE_REQUEST_TIMEOUT.

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?

Four tight sentences, front-loaded with the core question ('Is the PCE answering, and how fast'), followed by endpoint, return shape, failure semantics, and the operational trigger. No sentence is filler.

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

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

For a zero-parameter diagnostic tool with no annotations and no output schema, the description fully compensates by specifying the call, the response fields, the error content, timeout interpretation, and bounded-wait controls. An agent has everything needed to invoke and interpret it.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing parameter-wise for the description to add or omit.

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

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

States a specific verb+resource: it probes GET /health to determine whether the PCE is answering and how fast. This is clearly distinct from sibling tools like check-pce-credentials-status or get-workloads, and even names the exact endpoint being called.

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

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

Gives an explicit usage trigger -- 'run this first when any other tool returns tool_timeout' -- which is strong operational guidance. It does not explicitly distinguish itself from the related check-pce-credentials-status sibling, so this is clear context rather than full when/when-not routing.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses that secrets are never revealed and explains the three possible `mode` values plus the hybrid-mode caveat that a user may actually have run as shared. It stops short of explicitly declaring read-only/idempotency or error behavior, but the mode disclosure is meaningful 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?

Purpose is front-loaded in the first clause, followed by the mode explanation. The final hybrid-mode sentence is dense and jargon-heavy but earns its place as the only documentation of an undocumented output field.

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

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

For a zero-parameter, annotation-less, output-schema-less tool, the description supplies the key missing surface: what `mode` means and how hybrid mode can misattribute the caller. Remaining gaps (read-only confirmation, error cases) are minor.

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?

Zero input parameters, so the baseline is 4. The description goes further by documenting `mode` semantics (per_user/shared/stdio) that would otherwise be invisible, though that is an output field not present anywhere in the provided schema.

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

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

States a precise verb and resource ('Check which PCE credentials apply to the current user') plus scope ('without revealing secrets'), which cleanly separates it from register-pce-credentials and delete-pce-credentials. An agent can identify it as the read-only credential-status probe without opening any schema.

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

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

Usage is implied by the read-only 'check ... status' framing and by contrast with the register/delete siblings, but the description never explicitly states when to call this versus those tools or any preconditions. Adequate but leaves routing to inference.

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

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

With no annotations, the description carries the full burden and does so: 'Read-only', no score, capped pulls never PASS (EXCEPTION), unknown scope is an error, T10/T12/T13 land in not_run, and it discloses query cost in concrete pulls. This is unusually rich behavioral disclosure.

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

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

One dense paragraph, front-loaded with purpose, then test list, return shape, edge-case rules, and cost. Despite length every sentence carries distinct information; nothing is redundant.

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

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

No output schema, but the description specifies the return object {result: PASS|FAIL|EXCEPTION|NOT_TESTED, measured, rows, evidence}, the not_run behavior, rows_total/rows_truncated, and query cost. Complete enough for an agent to invoke and interpret correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning beyond the schema - PCI packs use 90-day lookback, pversion is echoed as policy_version, and the capped-result consequence for max_results - which justifies above baseline.

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

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

States a specific verb+resource (audit evidence for segmentation controls per app/env scope pair) and enumerates the exact tests T1-T9, T11, T14 it runs, plus what it returns. The agent can distinguish this from siblings like compliance-check or find-unmanaged-traffic from the description alone.

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?

Explains defaults (all runnable tests), the always-collected T1 inventory, that unknown scope labels are errors listing valid values, and that framework requirement mapping lives in illumio://compliance/* resources. It gives strong context but does not explicitly name a sibling alternative or when-not to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does well by stating this is a comparison operation that 'shows' changes, strongly implying a non-mutating preview rather than an actual provisioning action. It also discloses exactly what categories of changes are reported (new, modified, deleted), though it does not discuss output format, limits, or side effects.

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 focused sentences with no filler. The action and purpose are front-loaded, and the output detail is compressed into a single clear list. 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 the tool's low complexity (one optional enum parameter, no required inputs, no nested objects), the description is largely complete for selection and invocation. It explains what the tool does, why you would use it, and what kinds of results to expect. The absence of an output schema or more explicit return-format details is a minor gap, not a blocking one.

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 documents the single parameter fully with an enum, a default, and a description, so schema coverage is 100%. The tool description adds little parameter-specific meaning beyond listing resources conceptually; the baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description begins with a clear, specific action: 'Compare draft vs active policy' and names the resource (policy) plus the purpose ('to see what would change on provisioning'). It also enumerates the output categories (rulesets, rules, IP lists, services), making the tool's function distinct from siblings like provision-policy or get-rulesets.

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

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

The phrase 'to see what would change on provisioning' implies this is a pre-check tool used before applying a draft, which provides some usage context. However, there is no explicit when-to-use/when-not-to-use guidance and no named alternatives or exclusions, so the guidance is implied rather than stated.

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

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

With no annotations, the description carries the burden well: it discloses that analysis runs against DRAFT policy and recent traffic rather than active policy, that results are heuristic and score-summarised, and that unknown scope labels fail rather than widening. It stops short of stating read-only safety, lookback implications, or result stability/rate behavior, leaving a small gap for an unannotated tool.

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

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

Three sentences, front-loaded with what the tool is, then the exclusion/alternative, then the scoping gotcha. No filler and no repetition of schema content.

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

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

Four all-optional parameters and no output schema are handled adequately: inputs are documented in the schema, the tool's purpose and limits are described, and the output is characterised as a score. The one remaining gap is what the score response actually contains (per-framework breakdown? findings?), which matters since there is no 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by clarifying the failure mode of app_name/env_name (unknown label = error) and by pointing to the illumio://compliance/* resources for framework guidance. It does not explain how lookback_days interacts with the heuristic scoring beyond the schema text.

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

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

States a specific verb+resource ('check policy posture against a framework'), names the supported frameworks, and describes the mechanism (keyword-routed heuristics on draft policy plus recent traffic) and output shape (a score). It is explicitly differentiated from the sibling collect-compliance-evidence, so an agent can tell them apart without opening either schema.

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

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

Explicitly positions itself as a 'first look' and states when NOT to use it ('Not audit evidence: for per-test results from ACTIVE policy for an app/env scope use collect-compliance-evidence'), naming the alternative and the selecting condition. It also adds a scoping rule — an unknown app_name/env_name label is an error, not an estate-wide run — which prevents a common misuse.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden and meets it: it flags 'WRITE OPERATION: changes PCE state,' discloses that gated clients pause for user approval, and warns that 'the call has not failed and must not be retried while waiting.' It also discloses the priority-ordering behavior (override deny blocks above all). This is exactly the operational context an agent needs to avoid retrying a write that is merely awaiting approval.

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 the core action, then structured with a numbered list for processing order and an all-caps 'WRITE OPERATION' flag for the critical warning. Every sentence carries distinct information — purpose, priority semantics, use cases, exclusion, order, and retry behavior — with no filler or repetition of schema content.

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

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

For a 7-parameter write operation with no annotations and no output schema, the description covers the invocation semantics, use-case selection, priority behavior, and the approval-gating pause comprehensively. The remaining gaps are minor: it doesn't state what a successful response returns or how conflicts with existing rules are handled. These are non-blocking 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 100%, so the baseline is 3. The description adds meaning on top by explaining the full rule processing order (1-5), which gives the override_deny parameter its operational weight, and by reinforcing the 'must not happen under any circumstances' semantics. It does not add much for consumers/providers/ruleset addressing, but the schema already documents those thoroughly.

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: 'Create a deny rule in an existing ruleset,' and immediately defines what a deny rule does (blocks specific traffic, processed after allow rules). It clearly distinguishes override deny rules from regular deny rules, and the tool is unambiguously differentiated from siblings like delete-deny-rule, update-deny-rule, create-ruleset, and create-ringfence.

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 explicit when-to-use guidance: override deny for 'emergency isolation, hard compliance blocks, or active attack response' and an explicit exclusion — 'NOT for normal segmentation or ringfencing.' The numbered processing order also tells the agent where deny rules sit relative to allow rules. The only gap is that it never names the alternative sibling tool (e.g., create-ringfence) for the normal segmentation case, leaving that to inference.

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

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

With no annotations, the description carries the full burden and does so effectively: it explicitly labels this a 'WRITE OPERATION' that changes PCE state, and explains the approval-gating behavior in clients (call pauses, not failed, must not be retried). This is critical context beyond what any structured field provides.

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?

Four sentences, front-loaded with the core purpose, then the entry constraint, then the write-operation warning and client-gating detail. Every sentence contributes essential information without repetition or filler.

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

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

Given the tool's complexity (5 parameters, no annotations, no output schema), the description is complete enough: it covers what the tool does, how to call it (at least one entry), the write side effect, and the client-specific approval behavior. It does not need to explain return values since no output schema exists.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds a meaningful constraint not present in the schema—'At least one entry is required' (the schema only requires 'name')—which helps the agent avoid invalid calls. It also repeats the input types (ranges, FQDNs) but goes beyond schema by clarifying the minimum content requirement.

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

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

States a specific verb ('Create') and resource ('IP List') and enumerates the input types (IP ranges, FQDNs, or both), which clearly distinguishes it from sibling tools like update-iplist and delete-iplist. An agent can identify the tool's function without opening the schema.

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

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

Provides clear context: it creates a new IP list and requires at least one entry. However, it does not explicitly state when to use this versus update-iplist or mention any exclusions or prerequisites. The usage is strongly implied but not fully elaborated with 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?

With no annotations, the description takes on the transparency burden. It explicitly states this is a write operation that changes PCE state and explains the approval-gating behavior in clients, including the key caveat that the call must not be retried while waiting. This is valuable behavioral disclosure beyond the schema.

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

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

Two sentences and no filler. The first sentence states the action, and the second delivers a necessary operational warning. Well front-loaded and appropriately 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?

The definition covers side effects and approval handling, which is important for a write operation. However, with 0% schema coverage and no explanation of key/value semantics, valid label types, response behavior, or potential uniqueness constraints, the description is not fully self-sufficient 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 0%, so the description must compensate for the undocumented key and value parameters. It mentions 'a specific type and the value' but never explicitly maps type to the key parameter or defines allowed/formatted values. An agent would struggle to confidently populate the parameters.

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

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

The description names a concrete operation—'create a label'—with a resource (label) and context (PCE). It is not a tautology and is distinguishable from update-label and delete-label. However, the phrase 'a specific type and the value' is slightly vague and does not explicitly say key/value.

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 no guidance about when to choose create-label over update-label or delete-label, and names no alternatives or preconditions. The retry warning is about post-invocation behavior, not tool 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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It explicitly flags 'WRITE OPERATION: changes PCE state,' explains that gated clients may pause for user approval, warns that the call should not be retried while waiting, and details rule ordering and how deny rules are pushed to source workloads. This goes well beyond a generic 'update' warning.

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 information-dense, with a numbered list breaking down the generated rules and a clearly separated approval caveat. It is front-loaded with the core purpose. Some detail, such as selective-mode rule ordering, is repeated in the schema, so a couple of sentences could theoretically be trimmed, but the structure keeps it navigable.

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, nine parameters, and absence of annotations or output schema, the description is very complete: it explains side effects, approval behavior, generated rule types, and coarse-grained intent. The main gap is that it does not describe what the API returns or how to interpret the response after the approval completes, though that is not strictly required 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 100%, so the baseline is 3 and the description does not need to re-document parameters. It does add high-level context by explaining the overall policy structure and selective-mode rule ordering, but it does not add unique meaning for most individual parameters beyond what the schema already states.

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

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

The first sentence states a specific verb and resource: 'Create a ringfencing policy for an application.' It then distinguishes the tool's behavior from general policy creation by detailing the intra-scope and extra-scope rules it generates. This makes its function clear even alongside siblings like create-ruleset and ringfence-batch.

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: use this when you need a coarse-grained segmentation policy discovered from traffic flows. It explains what the result looks like and even warns about approval pauses in gated clients. However, it does not explicitly contrast itself with alternatives such as ringfence-batch or create-ruleset, so it lacks explicit 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly warns that this is a WRITE OPERATION that changes PCE state and describes the approval-pause behavior in gated clients, including the important warning that the call must not be retried while waiting. This is strong context, though it does not cover post-approval outcomes or failure semantics.

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 efficient sentences with no filler. The most operationally important facts—that this is a write operation and that gated clients pause for approval—are front-loaded, and every clause adds useful information.

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

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

The write/approval behavior is clearly conveyed and the schema covers most parameter semantics, but the description omits guidance on how this tool relates to the ring-fencing sibling tools and does not describe result/return behavior in the absence of an output schema. For a complex create operation with no annotations, this is adequate 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?

Schema description coverage is 75%, and the schema already provides rich parameter-level documentation for scopes, rules, ingress/egress services, and name uniqueness. The tool description itself adds no parameter-specific meaning, so it stays at the baseline rather than exceeding what the schema already provides.

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

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

The description states a specific verb and resource: 'Create a ruleset in the PCE', which clearly distinguishes it from update/delete ruleset tools and from workload/IP-list creation tools. However, it does not differentiate it from the closely related create-ringfence or ringfence-batch sibling tools, so it stops one step short of a top score.

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

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

There is no explicit guidance on when to use this tool versus alternatives, such as create-ringfence, ringfence-batch, or create-deny-rule. Mentioning 'support for ring-fencing patterns' hints at relevance but does not tell an agent when this generic ruleset creation path is preferable to the ring-fence-specific 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?

With no annotations provided, the description carries the full burden and explicitly states 'WRITE OPERATION: changes PCE state.' It also discloses that clients may pause for user approval and that retrying during the wait is incorrect. This meaningfully informs agent behavior beyond the schema.

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

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

The description is three sentences with no filler: purpose, critical parameter constraint, and an operational warning. Every sentence earns its place, and the most important usage requirement is front-loaded.

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

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

For a create tool with no annotations and no output schema, the description covers the essential selection, parameter constraints, side-effect, and retry behavior. It does not discuss duplication, authorization, or the return value, but those are less critical 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 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the at-least-one-of constraint, the consumer-side matching behavior of windows_egress_services, and the note that egress only takes process_name/service_name and must be paired with service_ports. This compensates well for what the schema alone does not convey.

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 and resource: 'Create a service in the PCE.' It then elaborates the three supported service definitions. It does not explicitly contrast with siblings like update-service or get-services, but the action and noun are specific enough for basic 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?

The description gives practical usage constraints: 'Supply at least one of service_ports, windows_services or windows_egress_services.' It also flags a conditional requirement for windows_egress_services needing a Windows VEN on the consumer. It does not explicitly name alternatives or when not to use this tool, so it misses the top benchmark.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly warns that this is a WRITE OPERATION changing PCE state and that gated clients may pause for user approval, adding important operational context beyond the tool name.

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 very concise, with two sentences that each earn their place: one for purpose and one for critical write-approval behavior. It is front-loaded with the core action.

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

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

Despite the useful gating warning, the description omits parameter guidance, return-value expectations, and any constraints on labels or IP address formats. Since there is no output schema and no annotations, these gaps leave the tool only partially specified for an agent.

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

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

Schema description coverage is 0% and the description provides no information about 'name', 'labels', or 'ip_addresses'. The description does not compensate for the schema's lack of parameter 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 states a specific action ('Create') and a specific resource ('an Illumio Core unmanaged workload in the PCE'), making the tool's purpose clear. It also distinguishes itself from sibling tools like update-workload and delete-workload.

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 for creating unmanaged workloads, but it does not explicitly compare with alternatives or describe when not to use it. It gives clear context for the operation but no exclusions or alternative routing.

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

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

With no annotations, the description carries the full burden. It explicitly discloses that this is a write operation that 'changes PCE state' and warns about the approval pause in gated clients, advising against retries. This is valuable non-obvious behavior. It doesn't cover side effects or error cases, but for a single-parameter delete it is strong.

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 with no filler. The purpose is front-loaded, and the critical operational warning follows immediately. Every word earns its place; the all-caps 'WRITE OPERATION' is a minor stylistic choice that doesn't harm 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 simple tool with one parameter and no output schema, the description sufficiently covers what it does and the most important runtime behavior (approval gating). Explicit return-value semantics would be nice but are not necessary given the simplicity and absence of an 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 coverage is 100%: the href parameter is fully described with an example path format. The description merely restates 'by its href' without adding new detail, 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 a specific verb ('Delete'), a specific resource ('deny rule from a ruleset'), and a selection mechanism ('by its href'). This clearly differentiates it from sibling tools like delete-sec-rule or delete-ruleset without needing to open schemas.

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

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

The context is clear: use this when deleting a deny rule. It does not explicitly name alternatives (e.g., update-deny-rule for modification), but the operation is unambiguous given the sibling set. The approval-gating note provides additional operational context, though it is more about behavior than tool 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly labels the operation as a WRITE OPERATION that changes PCE state, and discloses that gated clients pause for user approval, warning that the call has not failed and must not be retried. This is exactly the behavioral context an agent needs beyond the action itself.

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

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

Three tight sentences, each earning its place: action, parameter selection rule, and critical behavioral warning. The most important information is front-loaded, and there is no filler.

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

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

For a low-complexity tool with two optional parameters and no output schema, the description fully equips an agent to invoke it correctly. It covers resource, identification method, exclusivity constraint, operation type, and client-side behavior. Nothing essential is missing.

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

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

Schema coverage is 100% and both parameters have descriptions, so the baseline is 3. The description adds meaningful value by specifying the exclusive-or relationship between 'href' and 'name' ('but not both'), which is not captured in 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 opens with a specific verb and resource: 'Delete an IP List from the PCE.' This clearly distinguishes it from sibling tools like create-iplist, update-iplist, and get-iplists. No ambiguity about what the tool does.

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 instructs how to identify the resource: provide either 'href' or 'name' but not both. It clearly states the context for use ('Delete an IP List from the PCE'). It does not explicitly name exclusions or alternatives, but the operation is unambiguous and the identification rule is strong guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that this is a write operation that changes PCE state and that approval pauses are not failures, which prevents dangerous retries. This is strong transparency beyond what the schema offers.

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 brief and front-loaded with the core action and state-change warning. The only minor issue is the run-together phrasing 'PCE WRITE OPERATION', which could be misread, but overall every sentence earns its place.

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

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

For a simple two-parameter delete operation with no output schema, the description covers the most important behavioral context, especially the approval-gating and retry guidance. It is not fully complete because it omits parameter semantics and any side effects of deleting a label, but it is adequate for basic 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 schema has two required parameters, key and value, with 0% description coverage. The tool description does not explain what key and value represent, how they identify the label, or any constraints on their values. The names imply they are label identifiers, but the description provides no real semantic help.

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 ('Delete a label') and the target resource ('in the PCE'), and explicitly characterizes it as a write operation. It does not explicitly contrast with siblings like create-label or update-label, but the verb and resource make the intended operation clear.

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 useful operational guidance by warning that gated clients pause for approval and that the call must not be retried while waiting. However, it does not provide explicit guidance about when to choose delete-label over alternatives such as update-label or create-label.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers. It explicitly states this is a WRITE OPERATION that changes PCE state, discloses idempotency, and warns about approval pauses in gated clients with the crucial guidance that the call has not failed and must not be retried while waiting. This is exemplary behavioral transparency.

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 front-loaded: the core action is in the first sentence, followed by essential behavioral notes. Every sentence earns its place, covering action, idempotency, side-effect, and client-gating behavior without 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?

For a parameterless, no-output-schema tool, the description is complete. It tells the agent what is removed, what side effects occur, how to handle approval delays, and that failure is not implied. Nothing essential is missing.

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

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

The tool has zero parameters, so the baseline is 4; no parameter semantics are needed. The description accurately reflects that the operation targets the current user's credentials without requiring additional inputs, which fully covers the parameter dimension.

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 ('Remove') and a precise resource ('the current user's stored PCE credentials'), clearly distinguishing it from sibling tools like register-pce-credentials and check-pce-credentials-status. An agent knows exactly what operation this performs.

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 establishes when this tool is appropriate: remove stored credentials for the current user. It also adds important usage context by noting the operation is idempotent and safe to call even when no credentials are stored, so the agent need not pre-check. It does not explicitly name alternatives, but for a simple delete operation the usage 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly flags this as a WRITE OPERATION that changes PCE state and warns that gated clients will pause for approval, emphasizing that retries are inappropriate while waiting. This is valuable context beyond what the schema or name alone would 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?

Two sentences with no filler: the first fronts the core purpose and the second delivers a critical non-obvious operational warning. Every word earns its place, and the all-caps 'WRITE OPERATION' usefully emphasizes the mutation risk.

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

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

For a one-parameter destructive tool with no output schema and no annotations, the description covers the essential behavior: what is deleted, what changes, and how approval-gated clients behave. It does not describe post-approval responses or failure modes, but this is minor for such a simple operation.

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

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

Schema coverage is 100% for the single href parameter, and the schema already includes a descriptive example. The description merely says 'by its href' without adding format constraints, validation rules, or behavioral meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific action ('Delete a ruleset from the PCE') and the required input mechanism ('by its href'). This clearly differentiates it from sibling delete tools such as delete-workload, delete-deny-rule, and delete-sec-rule by naming the exact 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 phrasing implies the tool is used when a ruleset needs to be deleted by href, but it does not explicitly contrast this with alternatives like update-ruleset or delete-deny-rule. No exclusions or prerequisites are mentioned beyond what the schema already states.

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

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

With no annotations provided, the description fully carries the burden. It declares 'WRITE OPERATION: changes PCE state,' which is a critical side-effect disclosure, and goes further to warn that in gated clients the call pauses for user approval and 'must not be retried while waiting.' This is exemplary behavioral transparency for a mutation tool.

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

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

Four short sentences with no filler. The core action, sibling alternative, side-effect warning, and retry instruction each earn their place and are ordered logically, from definition to operation to caveats.

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

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

For a single-parameter delete tool with no output schema, the description supplies all essential context: what it does, when to use, side effects, and client-specific approval behavior. The only minor omission is what happens after approval, but that can be inferred from the call completing normally, so this is essentially 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 only parameter, href, has a 100% descriptive schema including an example. The description adds no extra parameter-level semantics, so it correctly rests on the schema. Baseline 3 applies by design.

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: 'Delete a single allow rule from a ruleset, leaving the rest of the ruleset intact.' It explicitly differentiates from the sibling delete-deny-rule by naming it and stating the condition ('For deny rules use delete-deny-rule'). This leaves no ambiguity about what the tool operates on.

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 explicitly tells the agent when to use this tool ('allow rule') and when not to ('For deny rules use delete-deny-rule'). The phrase 'leaving the rest of the ruleset intact' also signals that this tool is for single-rule deletion rather than deleting the whole ruleset. This is direct, actionable usage guidance.

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

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

With no annotations, the description carries the full burden and does well: it explicitly flags 'WRITE OPERATION: changes PCE state' and explains the approval-pause behavior in gating clients, including that the call has not failed and must not be retried. This is valuable behavioral disclosure beyond the bare delete action, though it does not mention irreversibility or permission requirements.

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

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

The description is compact and front-loaded: purpose first, then state-change warning, then approval-pause guidance. Every sentence adds distinct value with no wasted words.

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

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

For a simple two-parameter delete tool without an output schema, the description covers the essential operational context: the write side effect, the approval delay, and identifier selection. It could explicitly state that at least one of href or name is required, but this is reasonably implied and not a major gap.

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

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

Schema description coverage is 100%, so the schema already documents href and name. The description adds only a preference hint ('href preferred') without new semantic detail, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a service from the PCE.' This clearly distinguishes it from sibling tools like delete-workload, delete-iplist, or delete-ruleset. The resource scope (PCE service) is unambiguous.

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

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

The description gives parameter-usage guidance ('Identify by href (preferred) or name') but does not explicitly state when to use this tool versus alternatives like delete-workload or delete-sec-rule. The context is implied by the tool name and resource, but no exclusions or sibling comparisons are provided.

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

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

With no annotations, the description carries the full burden and does well: it labels the tool as 'WRITE OPERATION: changes PCE state' and warns that in gated clients the call pauses for user approval, adding that the call has not failed and must not be retried while waiting. This is significant behavioral context, though it does not discuss side effects or reversibility.

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, each earning its place: the action, the identification guidance, and the critical behavioral warning. It is front-loaded with the main purpose and contains no filler.

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

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

For a destructive operation with no annotations and no output schema, the description covers the essential facts: what is deleted, how to identify it, that it changes PCE state, and the approval-gating behavior affecting retries. It omits finer details like permanence or cancellation handling, but is strong for this tool's complexity.

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

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

The schema already provides 100% coverage for both parameters, including the fact that name is an alternative to href. The description reinforces this with 'href (preferred) or name' but adds no new semantic information beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'Delete a workload from the PCE.' This clearly distinguishes it from sibling tools like delete-deny-rule or delete-iplist, and even from update-workload and create-workload, by naming the workload as the 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?

It gives invocation-level guidance ('Identify by href (preferred) or name') but does not explicitly describe when to use this tool versus alternatives such as update-workload or other delete-* siblings. No exclusions or alternative routing is provided; the usage context is implied through the tool name and action.

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

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

With no annotations, the description carries the full burden. It does disclose the analytical nature ('Analyze traffic patterns', 'detect potential') and the key concept of bridge apps, implying a read-only, heuristic analysis. But it does not mention data dependencies, limitations, or whether results are approximate or require additional validation.

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

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

Two sentences, zero filler. The primary purpose is stated first, and the bridge-identification detail adds meaningful clarification without bloating the text.

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 moderately complex analysis tool with no output schema and no annotations, so the description needs to explain what the agent will receive and any important caveats. It gives only a high-level notion of output ('identifies apps that serve as bridges') and omits details about result structure, false-positive potential, or how the optional parameters shape the output. An agent would likely need to call it experimentally to understand the results.

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

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

The input schema covers 100% of the parameters with clear descriptions. The tool description adds nothing beyond the schema about how these parameters influence the analysis, 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 uses a specific verb ('Analyze') and resource ('traffic patterns') and clearly states the outcome: detecting lateral movement paths and identifying bridge apps. This is distinct from siblings like get-traffic-flows, which simply retrieve traffic data, so an agent can tell them apart.

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 makes the use case clear: when you need to find potential lateral movement paths or bridge applications. However, it does not explicitly contrast this with alternatives or state when not to use it, so the guidance is implied rather than spelled out.

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

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

With no annotations, the description carries the burden and mostly does: it discloses the return record shape (process -> external destination with port, protocol, user, policy decision, volume), the ranking behavior, and the FQDN-over-bare-IP preference. It does not state that the operation is read-only or whether results are scoped by PCE permissions, which is the remaining gap for a zero-annotation tool.

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

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

Two sentences, front-loaded with the core question, then the return shape, then the disambiguation against the sibling. No filler and nothing buried.

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

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

For a nine-parameter, zero-annotation tool with no output schema, the description supplies the return contract and the selection rule, which is what an agent most needs. Missing are permission/scope caveats and the only_named_processes attribution caveat, which currently lives only in the schema.

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

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

Schema coverage is 100%, so all nine parameters are already documented in the schema, making 3 the baseline. The description adds one genuinely useful cross-parameter constraint implicitly by noting FQDNs only apply to destinations, but it does not explain limit vs max_results or when to prefer lookback_days over start_date beyond what the schema says.

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

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

States a concrete verb and resource ('Find which processes talk to destinations outside this PCE's managed estate') and frames it as the shadow-IT/unsanctioned-egress question. It also explicitly distinguishes itself from get-traffic-flows, so an agent can pick between them without opening either schema.

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

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

Gives an explicit routing rule: use this instead of get-traffic-flows when the question is 'what is talking out', not 'show me all traffic'. That is a when-to-use plus a named alternative plus the condition that selects it.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does reveal the analysis process and the output, but it does not explicitly state that this is a read-only assessment or mention permissions, side effects, or underlying data sources. 'Assess' implies no mutation, but that is not made explicit.

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

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

The description is two concise sentences: the first states the outcome and method, the second states the deliverable. Every phrase earns its place, and the key purpose is front-loaded.

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

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

For a moderate-complexity assessment tool, the description covers what it analyzes, what it returns, and the inputs are fully covered by the schema. It lacks a score range or example output, but it is sufficiently explicit for an agent to select 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?

Schema description coverage is 100%: app_name, env_name, and lookback_days are already documented in the input schema. The tool description adds no parameter-level meaning beyond the schema, so it meets the baseline of 3 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 names a specific verb ('Assess') and a distinct resource ('whether an application is ready for enforcement'), and details the method ('analyzing traffic flows, existing policy coverage, and identifying potential gaps') and output ('readiness score and actionable recommendations'). This clearly differentiates it from siblings like get-traffic-flows or get-workload-enforcement-status.

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 the tool is for readiness evaluation before enforcement, but it never explicitly says when to use it versus related tools such as get-traffic-flows, get-policy-coverage-report, or compliance-check. There is no when-to-use / when-not-to-use guidance or naming of 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?

With no annotations, the description carries the full burden and does: it declares 'Read-only', discloses the three underlying data pulls, enumerates the per-endpoint payload blocks, and explains derived classifications (profile shapes with the numbers each test used). It also discloses non-obvious behaviors: noise classes are counted but suppressed from output, and the timeline bucket size changes with range under a shared spike rule.

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

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

Front-loaded with the operative question and then the disambiguation, so the agent gets the decision-relevant content first. The middle is dense and run-on (a long comma-chained list of endpoint fields), but each clause carries real information rather than filler.

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

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

For a 13-parameter tool with no output schema, the description supplies the return shape in detail (per-direction blocks, peers, ports, policy mix, timestamps) plus truncation/ranking semantics that live only in the schema. Nothing needed to call it correctly or interpret the result is missing.

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

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

Schema description coverage is 92%, so the schema already documents nearly every parameter. The description reinforces the `ip` mode and the include_noise gating, but largely restates what the schema says rather than adding new semantics; the field-level detail it provides (neighbourhood, admin flag) describes return values, not inputs.

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?

Opens with the exact question the tool answers ('Which IP addresses show up in traffic that the PCE does not know as a workload at all') and then formalizes the definition of 'unknown' precisely (no workload attached to that side AND not an interface address of any inventoried workload). It explicitly names and rules out the nearest sibling, find-unmanaged-traffic, so an agent can route without opening either schema.

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

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

Gives a clear discriminator against find-unmanaged-traffic ('no app label' vs. no workload plus no interface match) and states the two operating modes (list vs. profile-a-single-address with `ip`). It also states when noise endpoints appear (only with include_noise). Missing a short 'reach for this when…' framing for the broader tool family (get-traffic-flows, discover-process-egress), but the alternatives are largely addressed.

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

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

With no annotations provided, the description carries the full behavioral burden. It does usefully define the domain logic ('unmanaged' = no app/env labels on sources or destinations), but it does not disclose output shape, whether results are aggregated, query cost/scale implications, or anything about the return format — significant given the absence of an 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?

Two sentences with zero filler: the first states the action and subject, the second defines the key term and its significance. The core function is front-loaded and every clause earns its place.

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

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

For a 4-param tool with fully documented optional parameters and sensible defaults, the call contract is reasonably inferable. However, with no output schema, the description should explain what results look like (return format, ordering by 'top'), and it also lacks routing guidance relative to the traffic-related siblings — both are gaps an agent must resolve 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 coverage is 100%, so the baseline is 3 and descriptors already document all four parameters. The description adds genuine meaning beyond the schema by defining 'unmanaged', which clarifies the central concept the direction parameter ('relative to managed workloads') depends on, adding value the schema alone does not provide.

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 uses a specific verb+resource ('Find traffic involving unmanaged workloads or IP addresses') and defines the scope precisely: sources or destinations lacking app/env labels. The policy-blind-spot framing differentiates it semantically from sibling traffic tools like get-traffic-flows, though it never names a sibling explicitly.

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

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

Usage context is implied by 'representing potential policy blind spots' — the agent can infer this is a discovery/analysis tool for surfacing coverage gaps. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as get-traffic-flows or detect-lateral-movement-paths that might overlap.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It implies a read-only operation and lists the returned fields, but it does not explain behavior around filtering, max_results, pagination, or potential prerequisites/errors. This is acceptable for a simple getter 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 two concise sentences with no filler. The main action and scope are front-loaded, and the second sentence efficiently summarizes the return fields.

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 two-parameter getter with no output schema, the description covers the core purpose and the main output fields. It is slightly incomplete in terms of explicit usage guidance and behavioral caveats, but the schema fills in the parameter details.

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 does not add significant parameter-level meaning beyond what the schema already provides, but it does not need to because both parameters are already documented with clear descriptions.

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

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

The description states a specific verb (Get), a specific resource (container clusters), and the scope (registered in the PCE). It further distinguishes itself from workload-level sibling tools by naming cluster-specific output fields such as CLAS mode, kubelink version, and node count.

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: querying container clusters registered in the PCE and viewing their status/version details. It does not explicitly mention when not to use it or point to alternatives, but the scope is clear enough for a simple list/get tool.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does add context by explaining what the profiles represent and how they control pod management. However, it does not disclose read-only expectations, filtering interactions, pagination, or what happens when no cluster_href is provided (that detail is only in the schema).

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

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

Two sentences, front-loaded with the action and scope, followed by a concise explanation of domain meaning. Every sentence earns its place and there is no redundant wording or filler.

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

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

For a simple getter with three optional filters and no output schema, the description plus schema cover most invocation needs. However, the description alone does not mention how to discover the cluster_href (sibling get-container-clusters), nor what a typical response contains. It is adequate but leaves the agent to infer these details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema; the phrase 'for a container cluster' loosely aligns with cluster_href but doesn't explain filter semantics or combinations. The schema already handles parameter documentation adequately.

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

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

The description states a clear verb+resource: 'Get Container Workload Profiles for a container cluster.' It also adds a useful conceptual explanation of what these profiles are (mapping K8s namespaces to Illumio labels and enforcement modes). It does not explicitly distinguish itself from sibling tools like get-container-clusters or get-kubernetes-workloads, hence no 5.

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

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

There is no guidance on when to use this tool versus alternatives such as get-container-clusters, get-kubernetes-workloads, or update-container-workload-profile. The description implies a use case (inspecting profiles for a cluster) but never states conditions, exclusions, or preferred alternatives. The only usage hint (cluster_href behavior when omitted) lives in the schema, not the description.

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

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

With no annotations, the description carries the burden and does well: it discloses the per-request single-event-type PCE constraint, one-request-per-type fan-out, newest-first merging, max_results capping, and that event_types_queried echoes the list. It also flags which event names are verified versus merely documented, which is unusually candid. It still omits permission requirements, default time window, and whether results are read-only in practice.

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

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

Front-loads the purpose and payload, then moves to filtering, verification status, and request semantics. The single dense paragraph wastes little, though the verification caveat and request-fan-out details could be split for readability. Every sentence carries information.

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

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

No output schema exists, so the description must convey return values; it partially does by describing created_by, resource_changes, notifications, action, and the event_types_queried/unverified fields. It does not describe the full response envelope, pagination tokens, or default time range, which leaves some gaps for an 8-parameter tool, but the critical invocation semantics are 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?

Schema coverage is 100%, so the baseline is 3, and the description adds real value: it defines exactly which event_type strings belong to each kind, explains that event_type accepts a single string or an ORed list, that kind and event_type combine, and how max_results interacts with the fan-out. It does not add much on status, severity, created_by, or the timestamp parameters beyond what the schema already says.

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

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

States a specific verb and resource: 'PCE audit events as data', then enumerates the event payload fields. An agent immediately knows this retrieves audit event records, which no sibling tool does. Distinguishable from the policy/workload CRUD and traffic-flow siblings without opening the schema.

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

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

Extensive guidance on how to filter (kind vs event_type, OR semantics) but no explicit statement of when to use this tool versus alternatives, or when not to use it. Usage is implied by the audit-event framing, but there is no named alternative or exclusion.

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

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

No annotations are provided, so the description carries the full burden; it discloses the returned shape (ip_ranges, fqdns, is_default on the 0.0.0.0/0 or ::/0 list), that containment is evaluated server-side across CIDRs, spans, exclusions and both IP families. It stops short of stating read-only safety explicitly or pagination/limits behavior beyond the max_results parameter.

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

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

Front-loaded with the core action, then return shape, then the filtering semantics that matter most. Dense but every clause carries information; the final sentence is long but is the single most decision-relevant sentence in the 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?

With no output schema and no annotations, the description supplies the return structure (ip_ranges with from_ip/to_ip/exclusion/description, fqdns, is_default, matched_range) and the filter semantics an agent needs. Nothing critical for correct invocation is missing.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds real meaning by explaining the semantic gap between contains_ip (exact containment, honours exclusions, returns matched_range) and ip_address (substring on range text, never matches inside a CIDR). It also explains is_default, which is not a parameter but shapes filtering strategy.

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

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

States a specific verb and resource ('Get IP lists from the PCE'), adds scope ('optional filtering'), and distinguishes itself from the address-containment query path. An agent can tell it apart from siblings like create-iplist/update-iplist without opening a schema.

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

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

Explicitly routes the agent: use contains_ip for an exact 'which lists cover this address' answer, while ip_address is only a substring match on range text. It also explains how to combine contains_ip with is_default to separate 'in a real list' from 'only in Any'.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that the tool operates in 'CLAS mode' and shows policy sync state, which adds context. However, it does not mention pagination behavior beyond the max_results parameter, whether the operation is read-only, or what happens when cluster_href is omitted (though the parameter description partially covers that).

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 with no wasted words. The main purpose is front-loaded, and the second sentence adds useful output detail. It is appropriately sized for a tool with three parameters and no output schema.

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

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

The description is adequate for a read-style list tool, but with no annotations and no output schema, it could be more complete. It does not explain what 'CLAS mode' means, how policy sync state is represented, or how the tool behaves when no cluster_href is provided (though the parameter description covers the fallback). An agent could call it correctly, but some behavioral context is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minimal parameter meaning beyond the schema: it mentions labels and policy sync state, which relate to the output rather than the parameters. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb ('Get') and resource ('Kubernetes Workloads (CLAS mode) from a container cluster'), and lists what it shows (Deployments, Services, other K8s objects, labels, policy sync state). It is clear enough to distinguish from the sibling 'get-workloads' (which likely targets non-container workloads), though it does not explicitly name that sibling.

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: it is for Kubernetes/container cluster workloads managed by Illumio, and the cluster_href parameter description says 'If omitted, lists all clusters first,' which gives some behavioral guidance. However, it does not explicitly state when to use this tool versus alternatives like get-workloads or get-container-clusters, nor does it provide 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?

No annotations are provided, so the description carries the full burden. It communicates a read-only list operation with optional filtering, but it does not disclose response format, pagination behavior, or default handling of deleted labels. This is minimal but not misleading.

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 with no filler. It conveys the resource, operation, and key capability without redundant elaboration.

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

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

For a simple list tool with well-documented optional parameters, the description is adequate but lean. It does not mention what a label is, what the response looks like, or any default behavior, which matters since there is no output schema and no annotations.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters clearly. The description adds no parameter-specific meaning beyond calling the filters 'optional,' which is appropriate but does not elevate the score.

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 ('Get') and resource ('labels') with a clear source ('PCE'), and optional filtering is mentioned. It is immediately distinguishable from the label mutation tools like create-label, update-label, and delete-label.

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 is the tool to use when retrieving labels, but it does not explicitly state when to use it over alternatives or when not to use it. It provides no exclusions or comparative guidance, so usage context is only implied.

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

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

No annotations are provided, so the description carries full behavioral burden. The verb 'Get' clearly indicates a read operation, but the description does not explicitly state that it is non-mutating, nor does it mention pagination behavior or response characteristics. The domain context is helpful, but behavioral detail beyond the verb is limited.

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 with no filler: the first states the action and resource, the second provides essential domain context. The description is front-loaded with the primary purpose and each sentence earns its place.

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

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

For a simple list/retrieval tool with full parameter schema coverage and no complex behavior, the description is largely complete. It lacks an explicit output schema or description of the return format, but the concept of pairing profiles is defined well enough for an agent to know what the tool returns and when to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('name' partial match and 'max_results' default 50). The tool description adds no additional parameter-level semantics, but with full schema coverage 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 clearly identifies the operation as 'Get pairing profiles from the PCE' and explains what pairing profiles are, which is a specific resource not covered by any sibling tool. The phrase 'initial enforcement mode and labels for VENs' adds useful domain context that distinguishes this from other get-* 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 this tool is used when pairing profiles are needed, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No exclusions or sibling comparisons are provided, so usage guidance 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?

With no annotations, the description carries the full burden and does so well: it names the undocumented root-level endpoints probed, maps 403 to 'exists but this key is not allowed' (and discloses the authorization_failed audit event), maps 404 to 'not on this PCE version', and explains the 200 pass-through. It also warns that probing without permission writes an audit event and defines the `warnings` threshold (>=80% of a limit or above a soft limit).

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

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

Front-loaded with the core question, then ordered by data source, error semantics, and the warnings field. It is dense and somewhat run-on in the middle clause, but essentially every sentence earns its place by adding behavioral or return-value information.

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

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

No output schema exists, so the description must cover returns; it defines `warnings` and the three probe outcomes (403/404/200), which is substantial. It stops short of describing the shape of the metrics payload itself, but for a 2-param diagnostic tool the coverage is nearly complete.

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

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

Schema coverage is 100%, so both parameters are already documented, establishing the baseline of 3. The description reinforces the object-limit probing behavior and audit-event side effect but adds no syntax, format, or default detail beyond what the schema already states.

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

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

Opens with a specific, memorable framing: 'How full is this PCE, against its limits.' The verb+resource (capacity/limit assessment of a PCE) is unambiguous and clearly distinct from every sibling, none of which report capacity. An agent can select it without opening the schema.

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

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

The purpose strongly implies a diagnostic/health-check use case, but there is no explicit when-to-use or when-not-to-use wording, and no named alternative (e.g., check-pce-connection or enforcement-readiness) is contrasted. Usage is inferable but not stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the report's analytical purpose and the covered-vs-blocked framing, which is useful. However, it doesn't disclose whether the report is read-only, whether it triggers any background computation, or what the output format looks like. The description adds some behavioral context but leaves significant gaps.

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 with no filler. The core action and purpose are front-loaded, and the second sentence adds the use-case context. It earns its place, though it could be slightly more compact.

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 report-generation tool with no output schema and no annotations, the description should clarify what the report contains and how it's returned. The covered-vs-blocked framing helps, but an agent still doesn't know whether the report is a file, a JSON object, or a summary. Given the tool's moderate complexity and the absence of structured metadata, this is a clear gap.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the high-level concept of 'traffic flows' and 'policy'd' but doesn't add meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Generate'), a resource ('policy coverage report for an app'), and the report's purpose ('showing what traffic is covered by existing rules vs what would be blocked'). This clearly distinguishes it from sibling tools like get-traffic-flows or get-rulesets, though it doesn't explicitly name a sibling 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?

The description implies when to use it ('Helps understand how much of an app's traffic is already policy'd'), which gives an agent a clear context signal. However, it doesn't explicitly state when not to use it or name alternative tools for related tasks like get-traffic-flows-summary or find-unmanaged-traffic.

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

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

With no annotations, the description does real work: it discloses the per-ruleset extra request for deny rules ('filter where you can'), that username resolution needs GET /users and comes back null when the key cannot list users, and that timestamps/authors may be absent if the PCE omits them. It doesn't cover pagination behavior or what happens on empty results, so it stops short of full disclosure for an unannotated tool.

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

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

Very dense but nearly every clause carries information the agent needs, especially the render shapes since there is no output schema. It front-loads the return format rather than the core purpose, which is a minor structural weakness, and it is a single unbroken block that is harder 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?

With no output schema, the description appropriately documents the exact returned shapes (scopes, consumers/providers variants, ingress_services) so an agent can parse results. Combined with the cost warning about unneeded calls, this covers most of what's needed; only pagination/max_results behavior and empty-result handling are left to the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema by framing `labels` as scope-matching versus `actor_labels` as any-ruleset rule-level matching ('the policy that touches app X'). The pversion draft/active meaning is largely already in the schema, keeping it from a 5.

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

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

States a specific verb and resource ('Get rulesets and their rules, from draft or active policy') and makes clear it returns rules nested inside their rulesets. It does not explicitly name or contrast with read-side siblings like compare-draft-active or get-policy-coverage-report, so an agent must infer the boundary from the name.

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

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

Gives an actionable selection rule between the two filter params: '`labels` matches ruleset SCOPE; `actor_labels` returns only the rules that NAME those labels ... the policy that touches app X.' It also advises 'filter where you can' because of per-ruleset cost. There are no explicit when-not-use cases or named alternatives for the other read 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?

With no annotations, the description carries the behavioral disclosure burden. It explains that cached tools/list and response shapes are not refreshed on server changes, clarifies the semantics of the `unlearn` field, and states the no-PCE-connection requirement. This goes well beyond a basic changelog summary.

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

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

The description is compact and front-loaded: purpose first, then usage triggers and a behavioral caveat, then the no-connection note. Every sentence earns its place with no filler or redundant restatement.

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 optional-parameter introspection tool with no output schema, the description provides enough context for selection and invocation, including the stale-cache caveat and the unlearn behavior. The return structure is not detailed, but 'changelog' combined with the `since` parameter makes it sufficiently inferable.

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 fully describes both parameters, so the baseline is 3. The description adds value by explaining the `unlearn` field as listing behavior changes that invalidate earlier assumptions, reinforcing the purpose of `unlearn_only` beyond the schema text.

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 'What changed in this MCP server,' giving a clear subject and intent. Among the PCE-focused sibling tools, its scope is unambiguous even though it does not explicitly name a sibling 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?

The description provides concrete triggers: call when behavior mismatches expectations, after a mid-session update, or before relying on assumptions from earlier in a long session. It also notes that no PCE connection is required. It lacks explicit when-not-to-use guidance, but the context is strong.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It only restates the purpose; it does not explicitly state that this is a read-only operation, has no side effects, how filters combine (AND/OR), what happens with no filters, or any limits. 'Get' implies read-only, but that is not made explicit.

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

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

The description is a single, tight sentence with no filler. It front-loads the core purpose and filtering capability, making it appropriately concise 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?

With 7 optional parameters, no output schema, and no annotations, the description is too thin. It does not mention the return shape (e.g., list of services), filter combination logic, pagination, or default behavior for max_results. An agent would have to guess important invocation semantics.

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

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

Schema description coverage is 100%, so all 7 parameters are already documented in the input schema. The description adds only 'optional filtering' and no parameter-specific meaning beyond what the schema provides, 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 uses a specific verb ('get') and resource ('services from the PCE'), and mentions optional filtering. It is clear enough to distinguish from sibling mutation tools like create-service, update-service, and delete-service, though it does not explicitly name alternatives or scope nuances.

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

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

No explicit when-to-use or when-not-to-use guidance is given. 'Optional filtering' implies this is the tool for retrieving services with filters, but the description does not direct the agent away from or toward any sibling tools, leaving usage context to inference.

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

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

No annotations are provided, so the description carries the full burden, yet it discloses nothing beyond the bare operation. It does not state that this is a read-only query, how max_results or query_name behave, whether results are paginated, or what a returned flow record contains — meaningful gaps for a 13-parameter analytics query.

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 is efficiently sized, but it is not front-loaded with anything actionable and the 'comprehensive filtering options' clause is filler that could have been replaced with real guidance at no extra length cost.

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 13 parameters, no annotations, and no output schema, the description is far too thin: it does not explain the return shape, result caps, the purpose of query_name, or the source-vs-destination asymmetry that the schema only partially captures. An agent would be calling this largely blind.

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 54%, and the description contributes nothing parameter-specific — 'comprehensive filtering options' tells an agent nothing about include/exclude semantics, group_by aggregation, or the port/proto service objects. Parameters left undocumented in the schema (query_name, max_results, include_services, policy_decisions, exclude_workloads_from_ip_list_query) remain unexplained in both places.

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

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

States a specific verb and resource ('Get traffic flows from the PCE'), so an agent knows the core operation. However, it does not distinguish this from close siblings such as get-traffic-flows-summary, get-traffic-timeline, or find-unmanaged-traffic, and the trailing phrase 'with comprehensive filtering options' adds no discriminating information.

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

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

No when-to-use guidance, no when-not-to-use exclusions, and no mention of the summary/timeline siblings that overlap heavily. An agent must infer from the name alone whether it wants raw per-flow data or an aggregated view.

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

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

With no annotations present, the description carries the full disclosure burden, and it delivers the most important behavioral fact for an agent: the response shape (four named sections) and the cost tradeoff versus the raw flows tool. It stops short of stating permission/auth requirements, the hard response size limit, or pagination behavior, which leaves real gaps for a heavy read tool.

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

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

Three sentences, front-loaded with the action and return shape, and the section enumeration earns its length by telling the agent exactly what analysis it can answer without a follow-up call. No filler.

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

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

This is a 14-parameter tool with no output schema and no annotations, so the description has to compensate, and it largely does by describing the four output sections in useful detail. The filtering surface (most of those 14 params) remains under-explained, both in the description and partly in the schema, which is the one meaningful shortfall.

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 57%, so roughly half the 14 parameters lean on the schema alone. The description adds only an implicit hint about detail_level cost ("far smaller") and says nothing about query_name, max_results, policy_decisions, the include/exclude service pairs, or exclude_workloads_from_ip_list_query. Baseline 3 for a mid-coverage schema is appropriate here.

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

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

States a specific verb and resource ("Summarize traffic flows as structured JSON") and then enumerates the exact sections returned (by_process, external_destinations, blocked, app_to_app). It also explicitly positions itself against the sibling get-traffic-flows, so an agent can distinguish the two without opening either schema.

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

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

Names the alternative tool by name and gives the selection condition: use this for analysis because it is far smaller and answers the usual questions directly. The only minor omission is a reverse pointer back to get-traffic-flows for raw row-level detail, but the routing guidance is explicit and actionable.

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

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

With no annotations, the description carries the full burden and does it well: it explains bucketing by first_detected, that persistent connections smear across buckets, that rows_spanning_buckets/resolution_note quantify the smear, that counts become lower bounds at max_results, and the exact spike rule (>=3x median of non-zero buckets, worst multiple).

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?

Four sentences, front-loaded with the core purpose and the alternative-avoidance hint before the caveats. Some sentences are dense (the first_detected smearing clause), but nothing is filler.

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

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

For a 16-parameter tool with no annotations and no output schema, the description covers the key return concepts (bucket fields, rows_spanning_buckets, resolution_note, spikes/worst) and the main caveats. The filter parameters are only covered by schema, which is acceptable but leaves minor gaps.

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

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

Schema coverage is 75%, so the schema already documents many params; the description adds real semantics beyond it by explaining the spike threshold computation and the lower-bound behavior of max_results, though it leaves the include/exclude filter families entirely to the schema.

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

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

Opens with a specific verb+resource+scope: 'Time-bucketed flow counts from ONE Explorer query', and immediately specifies the four bucket sizes and zero-filling. An agent can distinguish this from summary/flow-list siblings without opening the schema.

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

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

Gives a concrete use case ('blocked flows per hour for app X') and explains why not to loop a summary query per bucket, which implicitly steers away from get-traffic-flows-summary. It never names sibling tools explicitly or states when-not to use it, keeping it 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It does add some behavioral context (grouping behavior and mixed-state detection) beyond the tool name. However, it does not disclose the response format, whether the operation is read-only, pagination behavior, or what happens when no workloads match.

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 with the core purpose front-loaded and a useful second sentence about mixed enforcement states. No wasted words, though the structure could be slightly improved by explicitly noting the read-only nature.

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 2 optional parameters, 100% schema coverage, and no output schema, the description is adequate but minimal. It explains what the tool does but not what the response looks like, which could matter for an agent deciding whether this tool provides the needed detail versus a more granular tool like get-workloads.

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

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

Schema description coverage is 100% (both parameters are described as optional filters), so the schema handles parameter documentation. The description adds marginal value by implying the filters map to grouping dimensions (application and environment), but it doesn't add syntax or format details beyond the schema.

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

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

The description clearly states a specific verb ('get'), a resource ('enforcement mode status'), and adds context about grouping by application/environment and identifying mixed states. This makes the purpose understandable, though it doesn't explicitly distinguish it from related tools like get-workloads or get-rulesets.

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 (to check enforcement status across workloads) and mentions optional filtering via parameters, but it provides no explicit guidance on when to use it versus a sibling tool, nor any exclusions or alternatives. The usage context is clear enough but not explicitly stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the scale/breadth tradeoff (tabular overviews of thousands vs. complete data on specific workloads), which is genuinely useful, but says nothing about pagination, the default result cap, or authentication/PCE-connection prerequisites implied by siblings like check-pce-credentials-status.

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

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

Two sentences, front-loaded with the action and then the key parameter tradeoff. Every clause earns its place and nothing is padded.

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

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

For a ten-parameter read tool with no output schema and no annotations, the description covers the one non-obvious parameter and the scale expectations well. It stops short of mentioning pagination or auth prerequisites, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so all ten parameters are already documented, establishing a baseline of 3. The description reinforces detail_level with a breadth-vs-depth framing, but adds no syntax or format detail beyond what the enum description already provides.

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

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

States a specific verb+resource ('Get workloads from the PCE') with no ambiguity about what is returned. However, it never distinguishes itself from close siblings in the list such as get-kubernetes-workloads or get-container-workload-profiles, so an agent must infer the boundary itself.

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

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

The description does give useful selection guidance for the detail_level parameter (compact for thousands, full for specific workloads, labels_only for breadth), which is a real usage decision. But it offers no when-to-use/when-not guidance for the tool itself versus the Kubernetes/container workload siblings, leaving tool-level routing to inference.

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

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

With no annotations, the description carries the behavioral burden. It frames the tool as read-only analysis ('Analyze traffic flows', 'Builds a graph', 'computes centrality metrics') and describes returned artifacts, but it does not explicitly state that no state is changed, nor cover edge cases such as insufficient flow data or permission requirements.

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

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

Three purposeful sentences: the first states the action, the second explains the computation, and the third gives the use case and output. No fluff, and the main verb is front-loaded.

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

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

For a read-only analysis tool with no output schema and no annotations, the description covers the important ground: purpose, method, return value, and why the result matters. It could add details on how to interpret scores/tiers or prerequisites, but it is not materially 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 100%, so the schema fully documents all three optional parameters. The description adds no parameter-specific meaning, but it also doesn't need to; 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 'Analyze traffic flows to identify infrastructure services', a specific verb+resource pair, then clarifies the method (app-to-app graph, centrality metrics) and output (ranked list with scores, classification tiers, connectivity details). This clearly differentiates it from siblings like get-traffic-flows or get-traffic-flows-summary, which are raw/summary traffic 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 explicitly grounds usage in a segmentation rollout context: infrastructure services 'should be policy'd first during segmentation rollouts.' This gives clear when-to-use guidance, though it does not name alternative tools or state when not to use it.

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

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

With no annotations provided, the description carries the full burden and does well: it explicitly flags WRITE OPERATION, notes PCE state changes, warns about user-approval pauses, and cautions that retries are inappropriate while waiting. It discloses the two-step token flow, though it leaves ambiguous how the token parameter is supplied since no token field appears in the schema.

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

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

Every sentence earns its place: purpose, scope, write warning, client behavior, and confirmation flow. The write warning is placed prominently and the two-step behavior is communicated in a compact sequence.

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 explains the operation well and partially covers return behavior by saying the first call returns a token. However, with no output schema and no token parameter in the input schema, the exact mechanism for passing the token back is unexplained, leaving an important gap 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 input schema already documents both parameters at 100% coverage, including the important 'provisions ALL pending changes' behavior for omitted hrefs. The description adds little beyond that, so the baseline score of 3 applies.

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

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

States a specific verb and resource: 'Provision pending draft policy changes in the PCE.' It clarifies exactly what changes state, naming the affected entity types and the draft-to-active transition, which distinguishes it from siblings like compare-draft-active or enforcement-readiness.

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?

Explains when to use the tool: to provision pending draft changes, either all pending changes or specific items by href. It does not explicitly name alternative tools or exclusions, but the described action and the two-step confirmation flow give clear usage context.

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

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

With no annotations, the description fully carries the behavioral burden, and it does so well: it flags the mutation via 'WRITE OPERATION: changes PCE state' and explains the client-gating pause, including the critical instruction not to retry while waiting. Overwrite semantics are also disclosed.

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 convey purpose, effect, and a crucial behavioral warning with no filler. The most important operational facts are front-loaded.

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

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

For a write operation with no annotations or output schema, the description covers the essential context: what changes, what becomes available, the approval pause, and retry guidance. Together with fully documented parameters, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description adds no parameter-level meaning, which is acceptable but does not raise the baseline.

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

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

The description names a specific operation ('Register (or overwrite) PCE credentials') tied to 'the current authenticated user' and states the concrete effect: all PCE tools become available in the session. This clearly distinguishes it from sibling tools like delete-pce-credentials and check-pce-credentials-status.

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 makes the intended use obvious: register/overwrite credentials for the current user so PCE tools become available. It does not explicitly contrast with alternative status/check tools, but the overwrite wording and availability effect give clear context for when to call it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly labels the operation as a WRITE OPERATION that changes PCE state, warns that gated clients pause for user approval, states that the call has not failed and must not be retried, and discloses the two-step token requirement. This is strong and goes well beyond the schema.

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

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

The description is compact and well-organized. It opens with the purpose, then adds auto-discovery context, connects to create-ringfence, and finishes with side effects and the two-step workflow. Every sentence contributes useful information with no fluff 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?

For a mutating, multi-step tool with no annotations and no output schema, the description covers the core behavioral contract: side effects, approval pause, retry guidance, and the token-return flow. It is slightly incomplete because the second-step token is not represented in the input schema, so an agent would still need to infer how to pass it back.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context around auto-discovery, which maps to auto_order, and explains the confirm-token workflow. However, it does not elaborate on apps, dry_run, or lookback_days, and it mentions a token to pass back without a corresponding input-schema field, a minor inconsistency.

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 first sentence states the exact action and resource: 'Create ringfence policies for multiple applications at once.' The description also references 'the same logic as create-ringfence,' which lets an agent distinguish this batch tool from the single-application sibling without inspecting schemas.

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

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

The description gives clear operational context: it is for multiple applications, can optionally auto-discover infrastructure services first, and it explains the approval-gating and two-step confirm-token flow. It does not explicitly state when to use create-ringfence instead of this tool, so it falls just short of full when/when-not guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly marks the operation as a WRITE OPERATION that changes PCE state, and it explains the approval-gated behavior in Claude Desktop/Claude Code, including the critical instruction that the call should not be retried while waiting. This is unusually transparent and actionable.

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 front-loaded: it states the purpose, gives the key action, and then prominently warns about write behavior and approval gating. Every sentence earns its place, with no redundant filler or buried-critical warnings.

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 4-parameter tool with 100% schema coverage and no output schema, the description covers the essential operational context: purpose, how to trigger management, mutation side effect, and approval pause behavior. It does not describe return values or prerequisites in prose, but for this tool the schema and description together are 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 every parameter. The description mostly rephrases what the schema says about managed and assign_labels without adding new syntax, constraints, or cross-parameter relationships. This 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 clearly identifies the verb ('Update'), the resource ('Container Workload Profile'), and the broader purpose ('manage Kubernetes pods in Illumio'). However, it does not explicitly differentiate this from sibling tools like update-workload or get-container-workload-profiles, so it stops short of full sibling distinction.

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

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

The description gives clear context and actionable guidance ('Set managed=true and assign labels to start managing pods in a namespace'), but it never says when to choose this tool over alternatives or when not to use it. There is no exclusion or alternative routing, so usage guidance 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.