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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real value: it discloses a degradation mode ('TLS checks are skipped when its secrets cannot be listed'), which an agent must know to interpret a clean result. It stops short of describing pagination or failure behavior on an invalid namespace.

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, return shape, prerequisite, alternative, and scope caveat — and the core action is front-loaded in the first clause. It is dense rather than padded, though the return-field enumeration is arguably redundant given an output schema exists.

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

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

For a two-parameter read tool with an output schema, the description covers everything an agent needs: what is validated, how to obtain a namespace, which sibling to use for the single-Ingress case, and the scope and TLS-listing limitations. Nothing required 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 description coverage is 100% for both parameters, so the baseline is 3. The description only implies namespace scoping and points at list_ako_ingresses as a source of valid names; it adds no syntax, format, or default-value detail beyond what the schema already documents.

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 with explicit scope: 'Validate every Ingress in one namespace', and immediately names the two things it checks (IngressClass and TLS secret references). It also distinguishes itself from both siblings by name, so an agent can route correctly 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?

Explicit when-to-use and alternatives: 'Run list_ako_ingresses first for namespace names; use diagnose_ako_ingress instead for one named Ingress.' It also states the boundary condition ('Covers one namespace only'), which is exactly the kind of disambiguation an agent needs before invoking.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: expired certs are included with negative days remaining, and unreadable-expiry certs are counted separately as 'unknown, not not expiring'. That edge-case disclosure is more than the annotations provide, though rate limits/pagination are unmentioned.

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 purpose, then the routing rule, then edge cases, with no filler sentences. The 'default 30' repetition is minor and the paragraph structure is 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?

An output schema exists, so return values need not be explained, yet the description still flags ordering (soonest first) and the unknown-expiry category. For a single-parameter read tool this is complete enough to call correctly.

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

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

Schema description coverage is 100% and the single 'days' parameter is fully documented in the schema, so the baseline is 3. The description restates the default of 30 but adds no format or boundary semantics (e.g., max value) beyond the schema.

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

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

States a specific verb+resource+scope: 'Check which SSL certificates expire within N days'. It explicitly distinguishes itself from the sibling list_ssl_certs, so an agent can choose 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 when-to-use rule: 'Use this instead of list_ssl_certs when you only want certificates near expiry.' The alternative and the selecting condition are both named, leaving nothing 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?

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds real behavioral detail beyond them: the exact validation targets (IngressClass 'avi'/'avi-lb', TLS secrets, backend Services) and a precise error contract distinguishing a true 404 'Not found' from any other failure, which is reported as 'could not be read' with the HTTP status. It stops short of describing permissions or rate limits, so 4 rather than 5.

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 purpose and then layered with validation scope, error semantics and routing in a logical order; every sentence carries usable information. The 'Returns annotations, a numbered issue list and kubectl fixes' clause is somewhat wasted since an output schema exists, which keeps it from a 5.

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-resource diagnostic with four annotations and an output schema, the description supplies everything an agent needs to call it correctly: when to reach for it, what it inspects, how errors are reported, and where to go next. Nothing material 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 name, namespace and context are fully documented in the schema and the description does not need to compensate. The description adds no param-level detail beyond the schema (the 'avi'/'avi-lb' values describe a validated field, not an input), so the baseline 3 applies.

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

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

Starts with a specific verb+resource ('Diagnose why one Ingress has no corresponding AVI Virtual Service') and immediately narrows the scope to a single Ingress rather than the fleet. It also names the siblings that frame its position (list_ako_ingresses, get_ako_logs, get_ako_sync_status), so an agent can place it in the workflow 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?

Explicitly states the precondition ('Use list_ako_ingresses first to find Ingresses lacking a VS') and the fallback path when this tool comes back clean ('try get_ako_logs and get_ako_sync_status'). It also declares the boundary of what it covers ('Checks configuration only'), which tells the agent when this tool is the wrong lever.

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?

Adds substantial context beyond the annotations: empty output means no change, credential values are shown as `<redacted>` by the skill (not the real value), and the moving-latest caveat explains why two runs can differ with no local change. That last note nuances idempotentHint honestly rather than contradicting it.

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

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

Front-loaded with the mode tag and core purpose, then layered caveats. Every sentence earns its place: redaction note, preview guarantee, and non-idempotence warning are all actionable.

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?

A read-only preview tool with an output schema, so return structure needn't be repeated; the description still explains the empty-diff semantics and the redaction behavior. Nothing an agent needs to call it correctly 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 baseline is 3; the description adds real meaning by explaining that empty chart_version resolves the registry's moving latest and recommending get_ako_version be read and passed to both callers. It goes beyond the schema's terse 'Empty = registry latest.'

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: pending Helm value changes not yet applied, with `[READ]` signaling the mode. It clearly distinguishes itself from upgrade_ako_config (this is the preview of it) and from get_ako_config (current config, not pending diff).

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

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

Explicit when-to-use: 'Use this before upgrade_ako_config — it runs the same command.' It also names the exact alternative (get_ako_version) needed when chart_version is empty. Nothing is left 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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the per-Ingress return shape, and importantly the heuristic shard-mode matching that can produce false 'Missing' results, with a mitigation (confirm via list_lb_pools). It stops short of describing volume/pagination, so not a 5.

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 [READ] tag and a one-line purpose, then usage and caveats in tight sentences. The 'Returns Type, namespace/name and Status' sentence is somewhat redundant given an output schema exists, but the rest 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 an output schema, annotations covering safety, and full schema description coverage, the definition supplies the remaining operational context an agent needs: when to invoke, what it returns, and how to validate ambiguous results. Nothing critical is missing.

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

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

Schema description coverage is 100% and there is only one optional 'context' parameter already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource with scope: 'List Ingresses with no matching Virtual Service or pool on the Controller.' This is clearly distinct from sibling read tools like list_ako_ingresses and check_ako_ingress, and from the reconciliation tool force_ako_sync.

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 says when to use it ('Use when get_ako_sync_status reports a mismatch'), names the alternative that reconciles ('force_ako_sync reconciles'), and adds a pre-condition caveat to confirm results via list_lb_pools. When/when-not/alternatives are all present.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and the description goes well beyond them: it documents the two-phase preview/apply protocol, the exact contents of blast_radius, the noop outcome for an already-disabled member, and the specific refusal conditions. For a destructive mutation this is unusually complete 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?

Front-loaded with the [WRITE] tag and the drain semantics, then the confirm protocol, then refusals and usage. Dense but every sentence carries decision-relevant content. The heavily nested parentheticals slightly reduce scannability, keeping it short of a 5.

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 tool with no output schema, the description covers both possible return shapes an agent will encounter (blast_radius payload on preview, "noop" on already-disabled) plus the refusal cases. Nothing needed to invoke it safely 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 the baseline is 3, but the description adds real meaning by framing confirm as a preview-versus-apply gate and explaining that the preview output must be surfaced to the user before applying. The deprecated confirmed alias is documented in both places, so it adds nothing there.

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

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

States a specific verb, resource, and mechanism: "Disable a pool member with graceful drain — existing connections complete, no new traffic." This is unmistakably differentiated from the sibling enable_lb_pool_member and from set_virtual_service_enabled, which it names 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?

Gives explicit when-to-use (maintenance, rolling deployments), a prerequisite (run list_lb_pool_members first for the server IP), the inverse tool (enable_lb_pool_member), and multiple when-not conditions (already disabled → noop; sole enabled member → refused; ambiguous IP → refused). The confirm workflow guidance — "Do not set confirm=True on your own" — is exactly the kind of decision rule an agent needs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false; the description reinforces the write nature and adds genuinely new context — the confirmation output and the fact that this does not add a member that isn't already present. It leaves the non-idempotent annotation unexplained, which is a minor gap for a tool an agent might expect to be repeatable.

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 [WRITE] tag and the action, then adds three short sentences that each carry information (return shape, prerequisite tool, precondition). No filler or redundancy.

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

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

With an output schema present, return details need not be elaborated, and the safety profile is covered by annotations plus the description's precondition. For a two-parameter mutation with full schema coverage, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the 'pool' parameter's schema text is unusually rich (literal matching, refusal of unknown names, not inferable from VS names), so the schema carries most semantic load. The description only adds the pool-membership constraint on 'server', which is baseline-appropriate given full coverage.

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

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

States a specific verb (Enable), resource (pool member), and effect (so it receives traffic again), immediately distinguishing it from the sibling disable_lb_pool_member. The '[WRITE]' prefix signals mutation type up front, so an agent knows exactly what class of action this is.

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

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

Gives explicit pre-call sequencing ('Use list_lb_pool_members first to verify the server IP') and a strong precondition ('The server must already belong to the pool — this adds nothing'). It does not explicitly name disable_lb_pool_member as the inverse or state when-not-to-use, but the routing guidance is otherwise clear.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description goes well beyond them: it discloses the dry-run default, the exact blast_radius contents, the requirement for explicit user confirmation, and specific refusal conditions (terminating pod, unreadable pod/Ingress list).

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 [WRITE] and the core action, then layered with preview semantics, refusals, and workflow ordering. Dense and mostly purposeful, though the confirmation-guardrail point is stated at length and could be tightened.

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, open-world mutation tool with no output schema, the description covers what to expect (blast_radius), what gets changed, refusal cases, and traffic-disruption risk. Nothing an agent needs to invoke it safely 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% (baseline 3), and the description adds policy meaning beyond the schema: the preview-vs-apply semantics of confirm and an explicit instruction not to pre-set it without user review. It does not add syntax detail for context or the deprecated confirmed alias, which remain schema-only.

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: 'Force AKO to resync all K8s resources with the AVI Controller,' and immediately distinguishes itself from siblings by naming diff_ako_sync and get_ako_sync_status as complementary steps. The [WRITE] marker further clarifies the operation class.

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

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

Explicit: 'Use when drift is detected,' directed to run diff_ako_sync first and get_ako_sync_status after, plus an explicit when-not ('Do not set confirm=True on your own because the user asked earlier'). Alternatives and preconditions are all named.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavioral context beyond them: raw kubectl output shape, the meaning of 'AMKO not deployed', failure behavior when kubectl cannot read the cluster, and that an unreadable GSLBConfig is reported rather than skipped.

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 [READ] tag and purpose, then layers in output shape and routing guidance; every sentence carries information. Slightly dense and prose-heavy but no filler.

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

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

With an output schema present, return values needn't be re-explained, yet the description still characterizes the output and error semantics. For a zero-param read tool, nothing an agent needs to call it correctly 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly notes it always reads the current kubectl context, which is the only 'input-like' behavior an agent needs to reason about.

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: retrieving AMKO (AVI Multi-Cluster Kubernetes Operator) GSLB status, and immediately contrasts it with the sibling get_ako_status. An agent can distinguish this from get_ako_status 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 scopes usage: 'Use this only for multi-cluster GSLB questions — for single-cluster AKO health use get_ako_status instead.' It names the alternative and the condition that selects it, and points to list_ako_clusters for context handling.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value beyond them: the return format ('YAML as helm reports it') and a scope caveat ('Only values supplied at install time appear; chart defaults do not'). It stops short of describing error behavior or pagination, but for a read tool this is solid.

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 [READ] marker and purpose, followed by three tight sentences covering return format, sibling routing, and the scope caveat. Every sentence carries distinct information; no filler.

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

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

With an output schema present, the description needn't explain return fields, and annotations already cover the safety profile. It still adds the install-time-only caveat that an agent would otherwise not know, and routes to the right sibling. Nothing needed to call it correctly 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?

Zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter guidance because there is nothing to parameterize; no gap exists to fill.

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

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

Specific verb+resource (reads the AKO Helm release's values) with enumerated content (controller IP, cloud name, network settings, feature flags). It distinguishes itself from the diff_ako_config sibling, so 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?

Explicitly states when to use it ('Use this first to read the live config') and names the alternative plus its selecting condition ('use diff_ako_config instead to see what an upgrade would change'). This is textbook 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered; the description adds genuine behavioral context beyond them: output is raw log text rather than a table, and only the running container's logs are returned (previous-container logs are unavailable). The '[READ]' tag is redundant with readOnlyHint, and no auth/rate-limit caveats are given, keeping it at 4.

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, front-loaded with the read tag and resource, then output format, then trigger conditions. Every sentence carries distinct information (scope, output shape, routing) with no repetition of the 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 zero-required-param diagnostic read with an output schema present and full annotation coverage, the description supplies everything the agent needs: what it retrieves, the output form (raw text, not tabular), the container limitation, and the upstream signals that should trigger the call.

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% — tail, since, and context are each documented inline with defaults and examples. The description adds no parameter syntax or defaults of its own; the 'running container only' note implicitly constrains what the params can address but is not parameter documentation. 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?

States a specific verb and resource (AKO pod logs) plus the diagnostic scope it covers: Ingress creation failures, sync errors, Controller connectivity. This distinguishes it from siblings like get_ako_status (health summary) and get_ako_config (configuration), 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 explicit trigger conditions tied to named siblings: 'Use when get_ako_status shows the pod unhealthy or diff_ako_sync reports a missing Ingress.' That is a clear diagnostic path. It stops short of stating when not to use it (e.g. use list_ako_ingresses for inventory rather than log forensics), so it is strong but not complete routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the returned fields, the negative-result workflow, and the scoping constraint that it only checks one namespace. It stops short of detailing failure modes or traversal behavior, so not a 5.

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 verb and resource, then scope, then workflow routing. Every sentence carries load: nothing is redundant filler despite the length.

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

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

With annotations covering safety, an output schema covering return values, and the description covering scope and decision workflow, an agent has everything needed to call this correctly and route to siblings on failure.

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

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

With a single optional parameter and 100% schema coverage, the schema already documents 'context' including its default. The description doesn't add syntax or format guidance beyond noting the one-context scope, so the baseline 3 applies.

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

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

States a specific verb (Check) and resource (AKO pod status), clarifies it operates in Kubernetes, and names its scope. The 'one context's AKO namespace only' note distinguishes it from the sibling list_ako_clusters without needing to open any schema.

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

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

Explicitly positions the tool as the 'First step for Ingress or LoadBalancer issues' and prescribes the follow-up path ('follow with get_ako_logs when it is not Running'). It also names the fallback tool (list_ako_clusters) and the condition ('if not found') that selects it.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it is a cheap, count-only check, and a mismatch is a false positive in AKO shard mode where many Ingresses share one VS. It does not discuss error behavior or rate limits, so it falls just short of the top.

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, front-loaded with the operation and its return, then the workflow ordering, then the caveat. Every sentence carries distinct information with no restatement of the name or 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?

Output schema exists, so return values need no explanation here, and the description supplies the two things an agent cannot infer: that this is a cheap pre-check before diff_ako_sync, and that mismatches are expected in shard mode. Nothing needed to call or interpret the tool is missing.

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

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

There is a single optional 'context' parameter with 100% schema description coverage ('K8s context name (optional)'), so the schema fully documents it. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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

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

States a precise verb and two concrete resources ('Compare the number of K8s Ingresses with the number of AVI Virtual Services') and names the output ('both counts and a match/mismatch verdict'). It is clearly distinguishable from diff_ako_sync, which it explicitly names as the finer-grained 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?

'Use this first as a cheap check, then diff_ako_sync for which objects differ' gives explicit ordering and names the alternative tool for the follow-up step. The shard-mode caveat adds a when-to-distrust condition, covering both when to use and when a result is not 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and open-world access. The description adds genuinely useful non-obvious context beyond them: the tag is the sole source, so a 'latest' tag is reported literally rather than resolved to a version number. That caveat materially affects how an agent interprets the result.

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 [READ] marker and the core statement, then usage, then the caveat — three short sentences with no filler. Every sentence carries distinct information (what, when, gotcha).

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?

An output schema exists, so return-value detail is unnecessary, and annotations carry the safety profile. The description still covers purpose, sequencing relative to siblings, and the tag-source limitation, which is everything an agent needs to call 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?

There is one optional parameter ('context') and schema description coverage is 100%, so the schema already documents it ('K8s context name (optional)'). The description adds no semantics about context selection or defaults, leaving the baseline of 3 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?

States a specific verb+resource ('AKO version running in a cluster') and immediately names the data source ('read from the pod's image tag'), which distinguishes it from get_ako_status, get_ako_config, and get_ako_sync_status. An agent can identify the tool's scope 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 explicit when-to-use conditions: 'check compatibility with the Controller' and 'before diff_ako_config or upgrade_ako_config so both target the installed chart.' It names the sibling tools it sequences against, so the agent knows both the trigger and the ordering.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context ('An SE hosting no VS reports 0, not an error'), an edge case that prevents misinterpretation, though it omits freshness/pagination behavior.

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

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

Front-loaded with a '[READ]' tag, then purpose, return shape, when-to-use with alternatives, and one edge-case caveat. Every sentence carries information; no filler.

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

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

With an output schema present, return values need not be detailed, and the description still summarizes them. A no-param read tool with rich annotations is fully covered 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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond what the empty schema already conveys.

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 ('Health of every Service Engine') and enumerates the returned fields (name, operational state, VS count). An agent can distinguish this from sibling reads like list_service_engines 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 scopes when to use it ('Use when VS health degrades to check if the issue is at the SE level') and names the alternatives (list_service_engines for management IP/SE Group, get_virtual_service_status for the affected VS), giving clear routing logic.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds information annotations cannot express: the window is immutable (12 samples, 5 min apart) and an empty result means no traffic rather than an error. That last point is a genuine behavioral caveat that prevents a misread.

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 one-line purpose, followed by return contents, the fixed-window constraint, the empty-result caveat, and sibling routing. Dense but every clause carries information; the only redundancy is the '[READ]' tag duplicating the readOnlyHint annotation.

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 read tool with an output schema, the definition covers purpose, timing, output nature, the sampling-window constraint, and empty-result semantics. An agent has everything needed to call it correctly without touching 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 description coverage is 100% and the single parameter is fully documented in the schema (exact, case-sensitive name sourced from list_virtual_services). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Performance metrics for one Virtual Service') and pins the scope to a fixed one-hour window, which distinguishes it from siblings like get_virtual_service_status and get_virtual_service_error_logs.

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 when get_virtual_service_status shows degraded health', and contrasts with get_virtual_service_error_logs for per-request detail. Both the trigger condition and the alternative are named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful, non-obvious behavior: a 50-line cap, a status>=400 filter, the returned fields, and the ambiguity of empty results. It doesn't mention pagination or whether logs are cached/real-time, but for a read-only tool this 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?

Three tight sentences, front-loaded with the read-only marker and the core capability, then the sibling routing and the empty-result caveat. 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?

An output schema exists, so return values need not be described, yet the description still summarizes the returned fields for fast selection. Combined with the routing rule and empty-result caveat, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the schema already documents the window syntax ('30m', '1h', '2d') and the exact vs_name lookup source. The description adds only the implicit scoping to one Virtual Service, so baseline 3 is correct.

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

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

States a specific verb (get/logs) and resource (error logs for one Virtual Service), and explicitly bounds the content (status 400 and above, up to 50 lines). It names the sibling it is not (get_virtual_service_analytics), so the agent can distinguish the two without opening schemas.

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

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

Explicitly says to use this instead of get_virtual_service_analytics for per-request detail, giving a clear selection rule between two similar tools. It also warns how to interpret an empty result (no errors vs capture disabled), which prevents a common misreading.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds non-obvious behavior: exact-match name resolution fails otherwise, and a failed runtime read is reported in-band with HTTP status while health becomes UNKNOWN. That failure-mode disclosure is exactly the extra context annotations cannot supply.

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 read tag and purpose, then failure behavior, then alternative routing. No filler; each clause carries operational information.

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

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

With an output schema present, return values need not be spelled out, and the description still characterizes the single-block shape and degraded/failure response. Combined with the prerequisite and sibling routing, an agent has everything needed 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 defines 'name'; the description goes beyond it by specifying exact-match semantics and the list-first workflow to obtain a valid value. This adds real meaning over the schema, though it is a single well-documented parameter.

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

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

States a specific verb and resource (detailed status for one Virtual Service) and enumerates the payload it returns (VIP, pool, health, connections, throughput). It explicitly contrasts itself with list_virtual_services ('one detail block, not a list'), so an agent can tell it apart from its siblings 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 prerequisite ('Use list_virtual_services first for the exact name') and routes to alternatives for adjacent needs ('get_virtual_service_analytics for metrics, get_virtual_service_error_logs for 5xx'). When/when-not and named alternatives are all present.

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

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

Goes well beyond the readOnly/idempotent annotations: it documents the failure mode ('Fails when no context could be read'), the semantic distinction that 'Unreachable'/'Unreadable' means unknown rather than absent, the kubectl-on-PATH prerequisite, and a latency warning because every context is probed.

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 [READ] tag and the core action, then the return semantics, prerequisites, and routing hint. Dense but every clause carries information an agent needs; 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?

With an output schema present, return values need not be re-explained, yet the description still clarifies the ambiguous status tokens and the failure condition. Nothing needed to invoke or interpret this tool correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 — there is nothing parameter-wise for the description to clarify or compensate for.

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

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

States a specific verb+resource+scope: 'List every Kubernetes context in the active kubeconfig and whether AKO is deployed there.' That clearly separates it from siblings like get_ako_status (single context) and list_ako_ingresses (different resource).

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

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

Explicitly positions itself as the entry point ('Start here for context names') and names the downstream alternatives (get_ako_status, get_ako_logs, diagnose_ako_ingress) with the condition that selects them. Routing is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the [READ] prefix is largely redundant. However, the description adds real behavioral context beyond them: the scope is all namespaces and the result covers 'the K8s side only', which warns the agent that Controller-side objects are absent. Pagination and auth needs remain unstated.

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 purpose, then returns, then routing; each sentence steers decision-making. The field enumeration is somewhat redundant with the existing output schema and the '[READ]' tag duplicates annotations, so a small amount of text could be trimmed.

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 a rich annotation set, an output schema covering return fields, and a single optional parameter, the description supplies everything else needed: scope, the K8s-vs-Controller boundary, and the follow-up tool path. Nothing required 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?

The single optional 'context' parameter is documented in the schema at 100% coverage ('K8s context name (optional)'), so the baseline of 3 applies. The description adds nothing about the parameter, such as whether omitting it uses the current context, though for one optional arg this is a minor gap.

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

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

States a specific verb and resource ('Inventory Kubernetes Ingresses across all namespaces') and enumerates the returned fields (Namespace, Ingress name, Host(s), IngressClass). It is immediately distinguishable from siblings like list_virtual_services and list_ako_clusters.

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 the entry point ('Start here ... then pass them to check_ako_ingress or diagnose_ako_ingress') and names when to use a different tool ('use diff_ako_sync for Ingresses with no Controller object'). Both the primary flow and an alternative branch are covered.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that it 'Reports configured state only, not live health-monitor results,' which is useful behavioral context beyond annotations. However, it does not mention rate limits, pagination, or error behavior.

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

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

The description is a tight, front-loaded paragraph: first the action, then the return fields, then usage guidance, then a caveat. Every sentence is relevant and no words are wasted.

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

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

The tool has an output schema, so return values need not be explained. The description covers purpose, usage, and a key behavioral caveat (configured state only). The only minor gap is lack of explicit mention of what the output schema contains (e.g., member names, IP format), but that is acceptable given the output schema exists.

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

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

Schema coverage is 100%, so the schema fully documents the 'pool' parameter, including exact matching and the warning not to infer it from a VS name. The description reinforces this by directing users to run list_lb_pools first, adding mild value beyond the schema. Baseline is 3, but the cross-tool guidance nudges this higher.

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

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

The description starts with a specific verb and resource: 'List the members of a pool.' It clearly distinguishes from sibling tools like list_lb_pools (which lists pools, not members) and enable/disable_lb_pool_member (which are mutations). The [READ] marker reinforces it as a read operation.

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

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

It explicitly says to 'Use before enable_lb_pool_member or disable_lb_pool_member' and 'run list_lb_pools first for the pool name.' This gives both prerequisite ordering and downstream usage, leaving little inference needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and the '[READ]' tag merely restates them. The list of returned fields is real added context but is also covered by the output schema, and nothing is said about pagination, auth, or rate limits. With annotations carrying the safety profile, this is adequate but thin.

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

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

Two short sentences, no filler: the read tag and resource are front-loaded, the return shape follows, and the sibling routing hint closes it. 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 zero-required-param, read-only list tool with full schema coverage, an output schema and complete annotations, this is nearly sufficient. The only soft spot is that pool-related prerequisites (e.g. whether a Controller connection must exist) are left implicit, which is 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?

Schema description coverage is 100% and the single vs_filter parameter is fully documented there (substring match, omit for all pools). The description adds no syntax or filtering nuance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Discover pools on the Controller') and enumerates the returned fields (Name, member count, Enabled, short UUID). It also distinguishes itself from the sibling list_lb_pool_members by positioning itself as the prerequisite call, so an agent can tell the two apart without opening schemas.

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

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

Gives explicit sequencing guidance ('Use this before list_lb_pool_members') plus the reason pools are often named differently from the VS that use them, which tells the agent when this tool is needed. It stops short of stating when *not* to use it or naming any alternative entry point.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds real value beyond them by disclosing that the call 'cannot be paged or filtered' and by naming the status values returned (e.g. OPER_UP) — a genuine operational constraint an agent must plan around.

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 lines, front-loaded with the verb and resource scope, then returns, then usage routing. Every sentence earns its place with no restatement of the name.

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

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

With zero parameters, an output schema covering return values, and annotations covering the safety profile, nothing an agent needs is missing. The description adds the non-pageable/non-filterable constraint and the sibling routing that the structured fields cannot express.

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 is 4. There are no arguments whose semantics need explaining, and the description correctly implies the tool is invoked without input.

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

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

States a specific verb and resource ('List Service Engines') and immediately disambiguates the domain term by glossing it as 'AVI data-plane VMs on the Controller'. It also enumerates the returned fields, so an agent can tell it apart from get_service_engine_health at a glance.

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

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

Gives explicit when-to-use ('inventory capacity or find an SE's name and IP') and names the alternative with the condition that selects it ('use get_service_engine_health instead for degraded VS health'). Nothing is left 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured behavior: the call returns Name, Subject, Expiry and Type per certificate and cannot be paged or filtered, which warns the agent about unbounded result size on large inventories. Minor deduction because the returned fields partially duplicate the existing 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?

Three short sentences, front-loaded with the read-only nature and the resource, then the return shape, then the routing rule. Every sentence earns its place and nothing is repeated.

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

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

For a zero-parameter, read-only list tool with full annotation coverage and an output schema, the description supplies everything needed: what it returns, that it cannot be filtered or paged, and when to prefer the sibling. No material gap remains for an agent to call it correctly.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument full-enumeration call and adds no misleading parameter guidance, but there is nothing parameter-level left for it to clarify.

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

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

States a specific verb and resource ('List SSL/TLS certificates stored on the AVI Controller') and immediately scopes the result set to the AVI Controller. The inclusion of '[READ]' plus the explicit naming of the sibling it is not (check_ssl_cert_expiry) lets an agent distinguish it from the other list_* tools 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?

Gives explicit when-to-use ('inventory or a certificate's exact name') and names the alternative with its selecting condition ('use check_ssl_cert_expiry instead for only the ones expiring soon'). It also warns that the call cannot be paged or filtered, which tells the agent not to look for filtering parameters.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the lower bar applies. The description still adds real behavioral context beyond them: the result cannot be paged or filtered, it carries no health score, and it returns all VSes in one call. This is exactly the operational caveat an agent needs before committing to a call.

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 compact sentences, front-loaded with the verb and resource, then the return shape and limits, then the routing hint. Every clause earns its place with no filler.

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

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

An output schema exists, so the description need not document return structure in depth, yet it correctly flags the key limitations (no paging, no filtering, no health score) that the schema cannot convey. Nothing needed to call this correctly 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?

Only one optional parameter (controller) with 100% schema description coverage, so the schema already documents it fully. The description adds nothing about the controller argument; 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?

States a specific verb and resource ('List Virtual Services on the AVI Controller') and immediately scopes what is returned (Name, Enabled, VIP, short UUID). An agent can distinguish this bulk-listing tool from the single-VS lookup sibling 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 states the sequencing: 'Use this before drilling into one VS with get_virtual_service_status,' naming the alternative tool and the condition that selects it. No inference required.

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

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

Annotations already declare destructive/non-idempotent, and the description adds substantial context beyond them: the exact blast_radius contents returned by the dry-run (context, namespace, pod name/uid/phase/restarts, Ingresses whose programming pauses), the uid precondition guaranteeing the measured pod is the deleted one, and the explicit refusal cases (pod already terminating, unreadable pod or Ingress list). It also warns of brief traffic disruption.

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 operation class and verb, then the mechanism, then the safety workflow. A few clauses (the uid precondition parenthetical) are dense but each earns its place; no filler or repeated restatement of the name.

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

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

No output schema exists, and the description compensates by enumerating the dry-run return payload. Refusal conditions, follow-up tools, and the irreversibility/traffic note are all present, so an agent has everything needed to call this destructive tool safely.

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

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

Schema coverage is 100% and the confirm parameter is already documented as the dry-run gate, so the description mostly reinforces what the schema says rather than adding new semantics. It does usefully connect confirm=False to the concrete blast_radius payload, but the deprecated `confirmed` alias is left to the schema.

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

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

States a specific verb+resource ('Restart the AKO pod') and immediately explains the mechanism ('by deleting it — its StatefulSet recreates it'), which distinguishes it from the read-only siblings like get_ako_status and get_ako_logs. The [WRITE] tag front-loads the operation class.

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

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

Gives explicit when-to-use ('AKO is stuck or after config changes'), explicit follow-ups ('Run get_ako_status afterwards, and get_ako_logs if the pod is not Running'), and a strong when-not/safety rule ('Do not set confirm=True on your own because the user asked earlier'). The preview-then-confirm workflow is spelled out as a required sequence.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is partly covered. The description nonetheless adds real behavioral value the annotations cannot: the preview/blast_radius contract, the 'noop' result for already-in-state VS, and the refusal condition. One soft tension: the 'noop' idempotency language sits awkwardly beside idempotentHint=false, though it is not a flat contradiction.

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

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

The '[WRITE]' prefix and the opening verb+resource sentence front-load the essentials, and the remaining sentences each carry a distinct rule (preview, user decision, noop, refusal). It is somewhat long and the 'they have not seen what it changes yet' clause is a mild restatement, but no sentence is pure filler.

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

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

No output schema exists, yet the description explains the return contract (blast_radius contents, 'noop' action), the preview/apply split, and the refusal precondition. For a destructive mutation tool with annotations already covering safety, nothing an agent needs to call it correctly 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 documents name, enable, confirm (preview vs apply) and the deprecated confirmed alias clearly, so the description is not required to carry parameter meaning. It mainly restates the confirm semantics and adds the user-decision rule, which is usage guidance rather than new parameter detail. 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?

States a specific verb and resource ('Enable or disable a Virtual Service') plus the consequence of the disable path ('stops all traffic to it'). It also distinguishes itself from the read-only sibling get_virtual_service_status by naming it as a prerequisite for checking state.

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 workflow: without confirm=True it previews only, the agent must show blast_radius to the user and get an explicit decision, and must not set confirm=True on its own. It also names the fallback path ('Use get_virtual_service_status first') for the refusal case, leaving nothing 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?

Explicitly describes the preview mode (returns blast_radius and helm_dry_run, changes nothing), the refusal conditions (failing dry-run, pending helm op, unreadable status), and that credentials are blanked to <redacted>. This is far beyond what the annotations (readOnlyHint=false, destructiveHint=false, non-idempotent) 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?

Well-structured with the write marker, preview behavior, and refusal conditions front-loaded. Slightly lengthy but every section earns its place; the anti-pattern warning about confirm=True is valuable and not wasteful.

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-adjacent write tool with no output schema, the description covers preview output shape, refusal paths, credential redaction, and the recommended prerequisite. Nothing critical is missing 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 schema already documents all four parameters including confirm, dry_run, confirmed, and chart_version. The description reinforces the confirm semantics but doesn't add syntax details beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Apply an AKO Helm upgrade) and resource (avi-system release, Broadcom OCI chart), and clearly marks it as a WRITE operation vs. sibling read tools like get_ako_config and diff_ako_config.

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

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

Explicit when/when-not guidance: it says to run diff_ako_config first, explains preview vs. apply semantics via confirm=True, and warns not to set confirm=True on the user's behalf. Routes to the right sibling (diff_ako_config) explicitly.

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