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

Beyond the destructiveHint annotation, the description discloses server-side apply with FieldManager=radar, conflict handling, multi-document failure behavior, and return content details, offering rich behavioral context without contradicting annotations.

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

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

The description is well-structured and front-loaded with the core purpose, with each sentence contributing distinct and useful information without redundancy or unnecessary detail.

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

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

For a tool with six parameters and no output schema, the description comprehensively covers modes, conflict handling, dry_run, verification, multi-document behavior, and return format, making it fully complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the rationale behind force (field ownership), the effect of dry_run, and the multi-document behavior, enhancing comprehension beyond the schema 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 clearly states it creates or updates a Kubernetes resource from a YAML manifest, with explicit details about modes and behavior that distinguish it from read-only sibling tools like get_resource and patch_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?

Provides clear guidance on when to use 'apply' vs 'create' modes and when to set force=true or dry_run, but does not explicitly name alternative sibling tools or state when not to use this tool in favor of others.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable context beyond annotations: it discloses log stream capture (current AND previous), event filtering, exclusion of Secret content, and startupBlockers conditions. No contradiction with annotations.

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

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

The description is a dense but well-structured paragraph. It is front-loaded with the primary trigger, then methodically covers bundle contents, GitOps path, use cases, and alternatives. Every sentence contributes necessary context for a complex diagnostic tool.

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

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

Given the tool's complexity (6 parameters, no output schema), the description is remarkably complete. It covers both workload and GitOps resource types, enumerates output sections, names failure scenarios, and directs to alternatives. No significant gaps.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description does not add significant new parameter-level meaning; it restates the kind options (workload vs GitOps) but the schema already documents each parameter 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 explicitly defines the tool's purpose: 'find the root cause / localize the failure' for broken workloads or GitOps reconcilers. It enumerates the exact data bundles included for workloads and GitOps resources, distinguishing it from sibling tools like get_resource or get_pod_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?

Provides explicit 'Use when' triggers with concrete scenarios (CrashLoopBackOff, OOMKills, etc.). Also gives clear exclusions: 'If you only need ONE facet... prefer the targeted tool' and 'For other CRDs or non-workload kinds, use get_resource'. This is exemplary 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 the tool read-only. The description adds valuable behavioral context: ranking order (spec/config changes first), best-effort field-level diffs ('when available'), and a performance comparison. It does not contradict the annotations.

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

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

Three dense, purposeful sentences. The most important usage signal is front-loaded, and every sentence adds either use-case context, behavioral detail, or parameter strategy. 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 read-only tool with no output schema, the description covers the when, what, why, and how: identifies symptoms, explains return content and ranking, gives performance tradeoffs versus alternatives, and offers filtering strategies. It is fully sufficient 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 coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining how to use parameters: 'Pair with since to bound the window', 'filter by namespace, kind, or name', and the important tip to 'Omit namespace when the relevant change may be outside the app namespace.'

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

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

The description clearly states the tool 'Returns recent meaningful changes ranked with spec/config changes first, including field-level diffs.' This is a specific verb+resource combination that distinguishes it from siblings like get_events or get_resource, which focus on raw events or static resources.

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

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

The description opens with explicit symptoms ('this worked earlier' or 'something broke after a deploy/config change') and names alternatives directly: 'This is often faster than reading ReplicaSet histories or individual audit/log streams.' It also provides concrete parameter guidance, including when to omit namespace.

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

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

Annotations already indicate readOnlyHint=true, but the description adds crucial behavioral context: audit findings are independent of operational health, empty findings mean no violations (not a failed check), and it respects user audit settings. This goes beyond annotations and prevents misinterpretation.

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 detailed but every sentence earns its place, front-loading the primary use case and then layering critical caveats. It is well-structured with categories and explicit contrast to sibling tools, making it highly informative without redundancy.

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

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

Given the complexity of audit semantics, the description fully covers interpretation guidance (empty findings = no violations, not non-compliant), independence from operational health, and respect for user settings. No output schema exists, so this level of behavioral detail is essential and provided comprehensively.

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

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

Schema coverage is 100%, so the schema already documents all parameters with descriptions. The description only re-states filtering by namespace, category, severity, and doesn't add additional semantic value beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: assessing static config posture/compliance, and explicitly contrasts it with operational health. It names the specific categories (Security, Reliability, Efficiency) and provides concrete examples, distinguishing it from siblings like 'issues'.

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 when to use: when deciding 'is this cluster well-configured / compliant?', and when not: for 'what's broken right now?' use the issues tool. This gives clear alternatives and 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?

Annotations already provide readOnlyHint=true, so the safety profile is known. The description adds behavioral context by explaining that it returns an overview for ranking suspects before drilling into get_resource or logs, and describes the scope (cluster vs namespace). It does not mention any limitations like permission requirements or performance, but given the annotation coverage, this is sufficient.

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 with useful information but not bloated. Every sentence adds value: purpose, return content, routing, and namespace guidance. The structure with a routing list is efficient and easy to scan.

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

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

Given no output schema, the description compensates by enumerating what the tool returns. It covers when to use, how to decide among siblings, and parameter semantics. For a single-optional-parameter tool, this is complete.

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

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

Schema coverage is 100% and the schema description already explains the namespace filter. The description adds usage nuance: 'Use namespace for app-local triage; omit it when the root may be cluster-scoped.' This goes beyond the schema and clarifies when to set vs omit the parameter.

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

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

The description clearly defines the tool's purpose: inventory-style cluster/namespace health triage, analogous to `kubectl get all` plus problem detection. It specifies the exact returned content (resource counts, failing pods, unhealthy workloads, Warning events, Helm status) and distinguishes it from siblings by naming what it is NOT for.

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

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

Provides explicit routing rules: 'unknown broken thing -> issues; content/name search -> search; service routing/dependencies -> get_topology or get_neighborhood; inventory/counts/Helm/events overview -> get_dashboard.' Also gives namespace usage guidance (use for app-local, omit for cluster-scoped), which is exceptionally 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 indicate read-only behavior. The description adds that events are deduplicated, sorted by recency, and include reason, message, and count. This provides useful behavioral context beyond the schema and annotations.

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

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

The description is two sentences long, front-loads the purpose and usage scenarios, and efficiently covers what the tool returns and when to use alternatives. No superfluous 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?

For a simple event-listing tool, the description covers the key aspects: what it returns (deduplicated events with reason, message, count), when to use it, and how it differs from 'issues'. It lacks an explicit time range for 'recent', but the limit parameter addresses pagination. Overall 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 coverage is 100% with clear descriptions for all parameters. The description does not add new semantic details about parameters but does provide usage context (e.g., 'after an overview points at a namespace'). This is adequate but not exceptional.

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

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

The tool's purpose is clearly stated: to retrieve recent Kubernetes Warning events for troubleshooting specific symptoms. It distinguishes itself from the sibling tool 'issues' by noting that 'issues' provides a ranked list of problems, whereas this tool returns raw events.

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

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

Explicitly states when to use this tool: after an overview points at a namespace/resource or when symptoms like scheduling errors occur. Also advises to use 'issues' first for a ranked issue list, providing clear differentiation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to repeat safety info. It adds value by disclosing that the tool returns owned resources and status, and that diff_revision_1/2 only take effect when 'include' contains 'diff'. This enriches the behavioral profile without contradicting annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by concise, high-signal details about optional parameters. There is no redundancy or filler; every sentence earns its place.

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

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

For a read-only tool with 5 parameters and no output schema, the description covers the main purpose, optional enhancements, and conditional parameter behavior. It does not explain the response format, but that is typically not required without an output schema, and the read-only annotation reduces risk. The description is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, but the description goes beyond the schema by explaining the accepted values for 'include' (values, history, diff) and the conditional semantics of diff_revision_1 and diff_revision_2. This adds meaningful usage guidance beyond parameter names and basic 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 clearly identifies the tool as retrieving detailed information about a specific Helm release, including owned resources and their status. This distinguishes it from sibling tools like list_helm_releases (which lists releases) and get_resource (generic resource access). The verb 'Get' and the resource 'Helm release' provide a specific, actionable purpose.

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

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

The description clearly implies usage for a single named Helm release rather than listing all releases, and it explains optional includes (values, history, diff) that can be requested. However, it does not explicitly name alternative tools or state when not to use this tool, so it slightly misses a full 'alternatives' clause.

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

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

The description reveals non-obvious behavioral details beyond the annotations: 'Nodes are RBAC-filtered; denied neighbors appear only as aggregate omitted counts.' It also discloses performance/characteristics like 'cheaper' and how profile all is 'heavier.' These traits are not present in annotations (readOnlyHint, openWorldHint) and add valuable context for the agent.

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 appropriately sized for a complex tool. It front-loads the primary use case, then explains the return behavior, profile options, and RBAC filtering in a compact, information-dense paragraph. Every sentence earns its place with no fluff.

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

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

Given the tool's complexity and the absence of an output schema, the description is thorough: it explains the BFS-expanded neighborhood, typical usage flow, profile behavior, hop limits, and RBAC filtering. It covers the necessary operational context without needing to restate parameter details already 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?

The input schema already provides 100% coverage of parameter descriptions, including defaults and behavior for hops, profile, max_nodes, etc. The tool description largely repeats this information (e.g., 'Hops defaults to 1 and maxes at 2') without adding materially new parameter-level semantics. 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 clearly states the tool's function: 'Returns the BFS-expanded topology neighborhood around one root.' It specifies the resource type (topology around a root) and distinguishes it from the sibling tool get_topology by noting it is 'usually cheaper and clearer ... once you have a suspect.'

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

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

The description provides explicit when-to-use guidance: 'Use when investigating cross-resource failures around a known resource...' and lists concrete scenarios (service routing, targetPort/selector problems, etc.). It also gives alternatives and exclusions, such as preferring get_topology in other situations and advising to use profile all only when auto yields a too-narrow result.

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

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

The description discloses that logs are filtered to diagnostically relevant lines and may fall back to tail lines, which is a behavioral trait beyond the readOnlyHint annotation. It also explains the grep parameter's server-side filtering behavior. While it does not detail output format or edge cases, it adds meaningful context without contradicting annotations.

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

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

The description is compact yet information-dense. It front-loads the primary usage condition ('Use only after narrowing'), followed by the core behavior, grep usage, and alternatives. Every sentence adds value without redundancy, achieving high clarity in limited space.

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

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

Despite having no output schema, the description sufficiently conveys the return type ('log lines') and fallback behavior. It covers when to use, how to use (grep, since, previous via schema), and when to avoid, making it complete for the tool's complexity. The schema covers parameter details, and the description fills behavioral context.

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

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

Schema coverage is 100%, providing baseline 3. The description adds extra semantics for the grep parameter, suggesting when to set it: 'when you know an error string, request path, service name, or trace id' and equating it to `kubectl logs | grep PATTERN`. This goes beyond the schema's minimal description and aids effective usage.

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

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

The description clearly states the tool's function: 'Returns diagnostically relevant log lines (errors, panics, stack traces, warnings) or falls back to recent tail lines.' It uses a specific verb ('returns'), names the resource (pod logs), and differentiates from related tools by emphasizing use for a specific Pod/container after narrowing scope, contrasting with broad incident 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?

Explicit guidance is provided: 'Use only after narrowing to a specific Pod/container.' It also states when not to use it, listing alternatives: 'For broad incidents, first use issues, get_dashboard, search, list_resources, or get_neighborhood' and 'If the target is a config value... use search rather than logs.' This clearly distinguishes this tool from siblings and gives concrete conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context beyond that: it mentions optional resourceContext rollups, describes the context tier options ('basic' vs 'none'), and clarifies it is not the best first call for broad incidents. This adds value without contradicting annotations.

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

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

The description is two sentences, front-loaded with usage guidance and key output details. Every sentence earns its place; no fluff or repetition of schema details.

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

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

Given the tool's read-only nature, 6 parameters, and no output schema, the description covers purpose, usage order, alternatives, parameter behavior, and expected return content. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with detailed descriptions for all 6 parameters. The description adds a few examples (e.g., ambiguous kinds for group) and cross-references to diagnose for full tier, but largely relies on schema. Baseline 3 is appropriate since the schema already carries most parameter meaning.

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 explicitly states what the tool does: 'Returns the resource's Kubernetes-shaped spec/status/metadata plus resourceContext when available (relationships, refs, issue/audit/policy rollups).' It clearly positions itself as 'the drill-down tool' and distinguishes from first-call tools and search.

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

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

Provides explicit when-to-use guidance: 'Use AFTER narrowing to one resource.' It names alternatives: 'Start with issues, get_dashboard, search, or list_resources to rank candidates; then call get_resource for the exact object.' Also instructs to use search for string lookups and group param for ambiguous kinds.

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

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

Even though readOnlyHint is true, the description adds substantial behavioral context: it explains the return structure (bindings, rule list, Pods for ServiceAccounts), the inclusion of inherited grants, and the `inheritedFromGroup` field to distinguish direct from inherited grants. This exceeds the annotation's minimal information.

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 reasonably concise for the complexity of the tool, with clear front-loading of purpose and use cases. Each sentence provides relevant information (returns, use cases, parameters, inheritance behavior), but it is slightly dense and could be tightened without losing value.

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

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

Given the tool's complexity and lack of output schema, the description fully covers what the tool returns and how to invoke it correctly. It also addresses edge cases (User/Group namespace omission) and inherited permissions, making it complete for an AI agent to select and use 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 value by explaining the conditional requirement for namespace and the distinction between ServiceAccount versus User/Group, which is not fully captured in the schema alone. This justifies a score 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?

The description clearly states the tool gets effective RBAC permissions for a Kubernetes subject, using the specific verb 'Get' and identifying the resource. It distinguishes itself from sibling tools by focusing on RBAC permissions, a unique capability among the listed 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 states when to use the tool ('is this SA over-privileged?', 'why can X do Y?', 'what's the blast radius...') and provides parameter-specific guidance (namespace required for ServiceAccount, omitted for User/Group). This gives clear context for invocation.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds behavioral context by listing the types of nodes and edges returned (Services, workloads, Pods, etc.) and the two view modes. It also implies that without a namespace the graph is cross-namespace, adding a scoping behavior not present in the schema. This goes beyond the annotations without over-explaining.

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

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

The description is efficiently written and front-loaded with the primary use case. Every sentence earns its place: it explains purpose, return value, view modes, namespace guidance, and points to an alternative tool. No redundancy or fluff.

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

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

Given the tool's moderate complexity, existing annotations, and absence of an output schema, the description is remarkably complete. It covers what the tool returns, how to scope it, which view to choose, and when to use an alternative. It adequately explains the output for an agent to invoke it correctly without needing additional context.

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

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

Schema description coverage is 100%, so the parameter descriptions in the schema fully document each field. The description repeats the view modes and namespace recommendation but adds no new parameter syntax or format details. Per the baseline for high schema coverage, a 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 clearly states the tool maps multi-service incidents or dependency graphs, returning Kubernetes resource nodes and edges. It distinguishes itself from get_neighborhood, which is for smaller focused graphs, and contrasts with inspecting resources one by one, making the purpose specific and 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?

Explicit guidance is provided: use for incident/dependency mapping, prefer scoped namespaces, choose view=traffic for routing/connectivity questions and view=resources for ownership/hierarchy. It also directs users to get_neighborhood when the suspicious root is already known, naming an alternative. This fully addresses when and when not to use the 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?

Annotations indicate read-only, but description provides valuable details: concurrent collection, server-side filtering to error/warning/panic/stack traces, deterministic regex, deduplication, and grep stage. This goes well beyond the annotation.

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

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

Description is concise yet complete: intentional use case, behavioral details, comparison to sibling, and exclusion guidance. Every sentence adds informational value.

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, but the description explains the filtering and aggregation behavior sufficiently for an agent to anticipate results. Minor omission: no mention of line limits or pagination, but these are in schema and less critical for the tool's core purpose.

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 already covers all 8 parameters with descriptions (100% coverage). The description adds context for grep behavior and defaults for kind, but most parameter meaning remains schema-driven. Baseline 3 applies.

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

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

Description clearly states it gets aggregated logs from all pods of a workload, naming supported kinds (Deployment, StatefulSet, DaemonSet). Distinguishes from get_pod_logs, making the purpose unambiguous.

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

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

Explicitly says when to use this over get_pod_logs ('when you need logs across all replicas'), and directs config/spec searches to the 'search' tool. Provides a concrete kubectl analogy for grep.

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?

Despite readOnlyHint, the description adds essential behavioral context: no source filter, each row carries a source label, diagnostic_context is 'triage context, not proof of root cause', and recent_changes/reason explain why it was attached. It also clarifies the separate axis of audit findings and PolicyReport violations, preventing misinterpretation. No contradiction with annotations.

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

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

The description is long and dense, but every clause serves a distinct purpose, and it is front-loaded with the primary use case. It loses a point for being a large unbroken paragraph with semicolon-separated clauses, which is harder to scan than structured bullets, but there is no waste.

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

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

For a read-only tool with no output schema, the description thoroughly covers what issues are returned, severity normalization, source categories, diagnostic_context, and the relationship to recent_changes. It also explains the broader workflow with siblings, making it complete for an agent to select and use 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 coverage is 100%, so the baseline is 3, but the description adds guidance beyond the schema: it explains the 'source' label is sliceable via the CEL filter and gives namespace usage advice ('Use namespace for app-local triage; omit it when the root may be cluster-scoped'). This enriches the meaning of the namespace and filter 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 has an explicit verb and resource: 'Returns a ranked list of currently failing resources' and clearly frames it as LIVE OPERATIONAL STATE with a specific decision trigger. It enumerates a detailed scope of failure modes and explicitly distinguishes itself from get_events and get_cluster_audit, making the purpose unambiguous.

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

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

The description explicitly states when to use ('what's broken right now?') vs. config posture, and names alternatives: 'For raw Kubernetes Warning events use get_events; for static best-practice / security-posture findings ... use get_cluster_audit'. It also provides post-issue routing guidance (diagnose, get_resource, get_neighborhood) and scoping advice for the namespace parameter.

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

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

The annotation readOnlyHint=true already establishes safety, but the description adds valuable behavioral detail about the return fields (status and health values) and the cluster-wide scope. It does not overpromise or hide any side effects, and there is no contradiction with annotations.

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

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

Two sentences, front-loaded with the core action, followed by return-value details and a usage recommendation. No redundant or filler content; 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 list operation with one optional parameter, the description covers the purpose, output, and usage context. Annotations cover the read-only safety, and no output schema is needed given the explicit field list. It is fully complete 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 only parameter (namespace) has a complete schema description with 100% coverage. The tool description adds no new semantics for the parameter beyond confirming it filters results, which is already clear from 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 clearly states the tool lists all Helm releases in the cluster, with specific output fields (release name, namespace, chart, version, status, health). The verb 'List' and resource 'Helm releases' are specific, and it naturally distinguishes itself from sibling tool get_helm_release which inspects individual releases.

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

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

The description explicitly says to use it 'to get an overview of what's deployed via Helm before inspecting individual releases,' indicating when this tool is appropriate and implying the alternative for deeper inspection. It lacks an explicit 'when not to use' statement, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety and completeness aspects. The description adds that the tool returns namespaces 'with their status' and frames it as a discovery operation, but does not disclose anything about output shape, pagination, or authorization, so it only modestly extends beyond the annotations.

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

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

The description is only two sentences, front-loaded with the core action and result. Every word adds value: it names the resource, specifies the scope, mentions status, and gives a use case. There is no fluff or redundant detail.

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

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

For a simple list tool with no parameters and no output schema, the description covers what it does and when to use it. It might be slightly richer if it mentioned the return format, but given the tool's simplicity and the annotations, this is 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?

The tool has zero parameters, so the base score is 4. The description does not need to explain parameters, and the input schema confirms no parameters exist. No additional semantic information is required.

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

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

The description clearly states the action (List) and the resource (Kubernetes namespaces), and specifies the scope ('all') and included detail (status). This distinguishes it from sibling tools like list_resources or list_helm_releases, which target different resource types.

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 advises when to use the tool: 'Use to discover available namespaces before filtering other queries.' This provides clear context for usage, though it does not explicitly name alternatives or when not to use it, which would merit a 5.

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

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

Annotations only provide readOnlyHint and openWorldHint, so the description carries the burden of explaining output semantics. It discloses the sources array codes, contributors array, worst-of health aggregation, first-source version priority, and sourcesErrored behavior with partial-result handling—far beyond what annotations convey.

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

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

The description is long due to the tool's complexity, but it is front-loaded with the core purpose and every subsequent sentence adds meaningful detail about output, usage, filters, or error semantics. 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 no output schema, the description fully explains return values (row-level fields, sources legend, contributors), aggregation rules, filter options, and failure handling. It is self-contained for an agent to use correctly without external documentation.

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

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

Schema description coverage is 100% with detailed parameter descriptions already present. The main description adds context around filter usage but does not significantly exceed the schema's parameter explanations; 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 clearly states the tool lists installed packages across multiple sources (Helm, labels, CRDs, Argo, Flux) with versions and health. It distinguishes itself from siblings like list_helm_releases and list_resources by explicitly framing this as an aggregation tool.

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

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

Explicitly states when to use this tool ('what's installed?', version lookups, orphaned operators) and names the alternative of combining list_helm_releases + list_resources. Also clarifies filtering by namespace/source/chart and explains behavior when sources fail, giving clear context for selecting this over siblings.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: it returns 'compact Kubernetes-shaped rows plus summaryContext by default (managedBy, health, issueCount)' and mentions a 'context' parameter option for 'none' to get bare rows. This goes beyond the annotation by clarifying the output shape and default enrichment, though it omits details like pagination or limits.

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

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

Three dense sentences, front-loaded with a clear use case, then output shape, then alternatives. No wasted words; 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?

With no output schema, the description adequately covers the return format (compact rows + summaryContext fields). It also provides usage boundaries. Slight gap: no mention of pagination, sorting, or error cases, but for a list tool with a moderate complexity this is reasonably complete.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description adds nominal value by naming example kinds ('pods/po, deployments/deploy...') and mentioning the default context behavior, but the schema already captures this. Baseline 3 is appropriate since the schema carries 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 clearly states a specific verb ('list') and resource scope ('jq-like namespace sweep' for known resource kinds like pods/deployments/services). It also distinguishes from siblings by explicitly naming get_resource as a follow-up and search for unknown kind/name searches.

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

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

Provides explicit when-to-use: 'when you know the resource kind' and 'before calling get_resource' to compare many similar resources. Also gives exclusions: 'For unknown kind/name searches, use search' and 'For broad health triage, use get_dashboard or issues first.' This is exemplary 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?

Annotations include destructiveHint=true, and the description adds valuable behavioral context by explaining the consequences of each action: trigger creates a manual Job run, suspend pauses the schedule (no new Jobs), resume re-enables the schedule. This goes beyond the bare annotation and informs the agent of the operational impact, though it does not discuss error handling 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 a single, efficient sentence that front-loads the core purpose and then lists the supported actions with concise explanations. Every clause adds information, with no filler or redundant phrasing.

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

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

For a simple management tool with three parameters, no output schema, and destructiveHint annotated, the description covers the essential behavior. It explains what each action does and the impact on the CronJob. Minor gaps include lack of information on preconditions (e.g., CronJob existing) or idempotency, but overall it is sufficiently complete for the 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?

While the schema already describes each parameter, the description adds substantial meaning to the action parameter by explaining what each action does. This helps the agent understand the semantic difference between trigger, suspend, and resume beyond the enum-like schema description. Name and namespace are self-explanatory, so no further detail is needed.

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

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

The description clearly states the tool performs operations on a Kubernetes CronJob and enumerates the exact supported actions (trigger, suspend, resume) with their effects. This distinguishes it from sibling tools like manage_workload or manage_node by specifying the resource and the precise operations.

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

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

The description implies when to use this tool: when a user needs to trigger, suspend, or resume a CronJob. It clearly defines the scope of actions, but does not explicitly mention alternatives or exclusions (e.g., 'use patch_resource for other modifications'). This is clear context without explicit exclusions, so a 4 is appropriate.

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

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

Annotations already include destructiveHint:true, which covers the destructive nature. The description adds semantic detail for each action (e.g., 'sync' triggers deployment, 'suspend' disables auto-sync) without contradicting the annotations.

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

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

The description is composed of two dense sentences that pack all essential usage rules: scope, per-tool action lists, and kind requirements. There is no filler or redundant 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?

Given the tool's complexity (12 params, multiple action sets per tool) and lack of an output schema, the description covers core decision points like which actions are valid for ArgoCD vs FluxCD and when kind is required. It could mention return values, but that is not strictly required when 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 descriptions cover all 12 parameters, but the description adds cross-cutting information: ArgoCD always uses Application kind, while FluxCD requires a kind parameter (kustomization, helmrelease, etc.). This relationship is not visible 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 clearly states 'Perform operations on GitOps resources (ArgoCD or FluxCD)' and enumerates action types for each tool, making it distinct from sibling management tools like manage_workload or apply_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?

It provides a clear scope (GitOps resources only) and differentiates actions by tool, which is sufficient context for selection. However, it does not explicitly mention alternatives or cases where another tool should be used instead.

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

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

Beyond the destructiveHint annotation, the description thoroughly discloses the behavioral impact: cordon prevents new pod scheduling, drain evicts all non-DaemonSet pods, and the options (force, delete_empty_dir_data, timeout) specify edge cases. This is rich, actionable behavioral detail that annotations alone would not provide.

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

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

The description is two sentences, front-loaded with the primary purpose, and then systematically lists actions and drain options. No redundant wording; every sentence adds value.

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

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

Given the tool's moderate complexity (5 parameters, 3 actions), the description fully explains the tool's behavior, parameter semantics, and safety implications. No output schema is present, but the description sufficiently covers what the agent needs to invoke it correctly. Annotations complement the description rather than leaving 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?

Although the schema covers 100% of parameters, the description adds significant meaning by explaining what each action does and how the drain options modify behavior (e.g., 'drain cordons the node and evicts all non-DaemonSet pods'). This goes well beyond the schema's terse property descriptions and helps the agent select correct parameter values.

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 'Perform operations on a Kubernetes node' and enumerates the supported actions (cordon, uncordon, drain) with specific effects. This distinguishes it from sibling tools like manage_workload or patch_resource, which target different resources or generic patching.

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 (to cordon, uncordon, or drain a node) without explicitly naming alternatives or exclusions. The uniqueness of the actions makes usage clear, but it stops short of saying 'use this instead of X', so it's a 4 rather than a 5.

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

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

Annotations include destructiveHint=true, so the description adds action-specific behaviors: restart triggers a rolling restart, scale changes replica count, and rollback reverts to a previous revision. It also ties parameters to actions, but does not detail side effects like pod termination or revision history limits.

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

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

Two sentences: first states the main purpose, second enumerates actions and provides a discovery hint. Every sentence adds value with no redundancy.

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

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

The description covers all supported operations, parameter requirements, target kinds, and the discovery step. The destructive nature is already provided by annotations. For a mutation tool with no output schema, this is adequate.

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

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

The schema covers all parameters (100% coverage), but the description explicitly states that 'replicas' is required for scale and 'revision' for rollback, adding conditional requirement semantics not fully captured in the schema.

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

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

The description clearly specifies that the tool performs operations on Kubernetes workloads and enumerates the three supported actions (restart, scale, rollback), distinguishing it from sibling tools like manage_cronjob or manage_node.

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 advises using list_resources or get_dashboard first to identify the target, providing a clear prerequisite. However, it does not contrast with alternative mutation tools like apply_resource or patch_resource, so no exclusions are mentioned.

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 include destructiveHint=true, but the description enriches this by explaining default return behavior ('compact post-patch state and dry-run preview diffs'), the effect of verify=false, and that JSON Patch calls include per-operation field checks. It also details the format requirements for each patch_type, adding significant transparency beyond the annotation.

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

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

The description is dense but every sentence delivers useful information: usage context, patch type specifics, and return behavior. It is front-loaded with the core purpose, then branches into details. Slightly long, but no redundancy, so it earns a 4 rather than 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?

Given the tool has 8 parameters, no output schema, and destructive annotations, the description covers the essential decision points: when to use it, how to choose patch_type, what the patch payload should look like, and what the response contains. It also mentions verify and dry_run behavior, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds meaning by providing concrete examples for json and merge patch types and clarifying how patch format relates to patch_type ('For patch_type=json, patch must be an RFC 6902 JSON Patch array'). This goes beyond the schema's generic 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 opens with a specific verb and resource: 'Patch one existing Kubernetes resource with JSON Patch, JSON Merge Patch, or strategic merge patch.' It clearly distinguishes itself from the sibling apply_resource by naming it and explaining when patch_resource is preferred, which goes beyond a generic statement.

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

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

The description explicitly states when to use this tool ('Use this for precise field/list mutations') and when to prefer an alternative ('Prefer this over apply_resource when you know the exact field to mutate and do not want to rewrite the full manifest or take broad server-side-apply ownership'). This gives clear context and an 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?

The description goes well beyond the readOnlyHint=true annotation by disclosing security-sensitive behavior: Secret content is intentionally not indexed to avoid leaking data through snippets. It also reveals query semantics (tokens AND'd), ranking, return format (ranked hits with snippets and summaryContext), and the limitation regarding warmed CRDs. No contradiction with annotations; it enriches them substantially.

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

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

The description is long but every sentence earns its place: purpose, security caveat, examples, modifier vs. enumeration guidance, CEL recommendation, return description, and CRD limitation. It is front-loaded with the primary purpose and structured logically, with zero filler or repetition.

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

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

Given the tool's complexity (5 parameters, no output schema, subtle query semantics), the description is complete: it explains what is searched, what is not (Secret values), how queries combine, how to narrow results, when to use alternatives, and what the response contains. No significant behavioral caveat is left undisclosed.

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

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

Although schema_description_coverage is 100%, the description adds high-value semantics beyond the schema: explicit query syntax (modifiers like kind:Pod, ns:foo), AND logic, examples, and guidance for filter/context parameters. This transforms dry parameter metadata into actionable usage knowledge, exceeding 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 opens with a specific verb 'Find' and defines the resource scope as 'resources by content/term match' when the user does not know which object contains a string. It clearly distinguishes itself from siblings by explicitly routing enumeration queries to list_resources and structural predicates to CEL filters, making it unmistakable what unique role this tool serves.

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 states when to use this tool ('when you do not know which object contains...') and when not to ('modifier-only queries are enumeration, so use list_resources', 'Use CEL filter for structural predicates'). It also provides a practical prerequisite ('cold CRDs need list_resources first'), giving clear decision guidance versus alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: it returns live metrics, joins with Kubernetes context, and explains that kind=workloads aggregates Pods from Deployments/StatefulSets/DaemonSets/Jobs. It does not contradict annotations, and while it omits rate limits or auth, the read-only nature is well-covered.

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

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

The description is well-structured and front-loaded with the most critical usage guidance. Sentences are compact and information-dense; every clause earns its place, covering when to use, what it returns, and how the kind parameter behaves, without redundancy.

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

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

Given the tool has no output schema, the description adequately explains the return shape (ranked metrics with pod status, readiness, restarts, owner workload, requests, limits). It also covers all kind variants and parameter behavior, making it complete for an agent to select and invoke the tool successfully.

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 parameters with descriptions, establishing a strong baseline. The description adds further semantic value by explaining how 'kind=workloads' aggregates Pods to specific workload types, which is not fully captured in the parameter description. This goes beyond the schema's basic field definitions.

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

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

The description states a specific verb and resource: 'Returns live metrics ranked like kubectl top pods|nodes | sort' and explicitly differentiates from siblings by positioning it as a pre-log investigation tool. It clearly defines the three kind variants, making its purpose unambiguous.

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

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

The description opens with explicit use cases ('Use when investigating high CPU, memory pressure, OOMKills, slow services, noisy pods, or uneven node load') and provides an alternative guidance ('Use before reading logs when the symptom mentions CPU, memory, GC, OOM, latency, or load'). This tells the agent when to choose this tool over log-focused siblings.

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