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

Annotations already cover read-only and idempotent behavior. The description adds useful behavioral context beyond that by stating that it reports warnings and blockers for bind mounts, depends_on ordering, and locally built images, which tells the agent what kind of analysis results to expect.

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 well structured, front-loading the purpose and then listing the mappings and blocker reporting. The first sentence is long, but every clause adds concrete mapping detail, so there is little waste.

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

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

Given the output schema exists, the description does not need to enumerate return fields. It covers the conceptual mappings, the blocker reporting behavior, and the read-only nature via annotations. It could be stronger on explicit path semantics and alternative tool routing, but it is generally complete for a one-parameter analysis tool.

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

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

Schema coverage is 0% and the description does not explicitly define what `path` should point to, though 'this project' implies a project root. With only one obvious parameter, the gap is tolerable but not fully compensated.

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

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

The description names a specific verb ('explain'), a specific resource ('this project's Docker concepts'), and the target mapping to Kubernetes. It also clearly distinguishes itself from raw inspection tools like inspect_project or inspect_dockerfile by focusing on migration-oriented mapping and reporting blockers.

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

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

The context is clear: this tool is for understanding how a Docker-based project maps to Kubernetes and what cannot be migrated automatically. It does not explicitly name alternatives, but the migration focus is strong enough that an agent can tell when to select it over inspection or manifest-generation 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?

The annotations already signal destructiveness and non-read-only behavior, but the description adds the approval requirement, the failure behavior around validation, and the dry-run execution semantics. These are operational details an agent could not infer from the schema or annotations alone.

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

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

The description front-loads the most important risk, then follows a logical order: danger, approval gate, validation prerequisite, and dry-run alternative. Every sentence carries operational weight 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?

For a destructive, approval-gated apply tool, the description covers the essential workflow: validate, obtain explicit approval, apply, or use dry_run. It is slightly incomplete only because path and namespace semantics are left to inference, but the output schema and annotations cover much of the remaining 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?

The description adds meaningful semantics for approved and dry_run, which are the most sensitive parameters. However, schema_description_coverage is 0%, and path (the only required parameter) and namespace are not explained at all, so the description does not fully compensate for the missing schema documentation.

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

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

The description opens with 'DEPLOY. This writes to the cluster and changes running workloads,' which clearly identifies the action, the target resource, and the impact. It also distinguishes itself from sibling tools by directing validation to validate_manifests and framing dry_run as the non-mutating alternative.

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

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

The description gives explicit when-to-use instructions: run validate_manifests first, and this tool refuses invalid manifests. It also gives a strict when-not-to-use rule: do not infer approval from the original request. The dry_run path is clearly presented as the safe alternative that needs no approval.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond this by explicitly stating 'Nothing is written to disk and no cluster is touched' and adds a critical behavioral rule: 'SHOW THIS PLAN TO THE USER before generating or deploying anything.' This is useful context not fully captured by 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 dense but efficient: the first sentence packs in the full plan contents, and the following two sentences deliver the critical behavioral constraints. It is a bit of a run-on, but every clause adds value and the most important instructions are front-loaded.

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

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

The output side is well covered and the output schema exists, but input semantics are severely underdescribed. An agent invoking this tool may not know what 'path' should point to or how namespace/image_registry affect the plan. Because one parameter is required and schema coverage is 0%, this is a meaningful completeness gap.

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

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

Schema description coverage is 0%, so the description carries the full responsibility for explaining parameters. It does not mention path, namespace, or image_registry at all, leaving the required 'path' parameter ambiguous and providing no meaning beyond the bare schema titles.

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

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

The description uses a specific verb ('Build') and specific resource ('concrete, reviewable migration plan') and enumerates exactly what the plan contains. It also distinguishes itself from sibling tools like generate_manifests and apply_manifests by explicitly stating this is done 'before generating or deploying anything'.

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

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

The description gives clear context: this tool is for producing a reviewable plan before any generation or deployment, and instructs the agent to show the plan to the user first. It does not explicitly name alternatives or state when not to use the tool, but the sequencing directive is strong enough to guide selection.

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

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

The description discloses that this is a read-only diagnostic operation by saying it 'gathers' resources and returns a diagnosis, consistent with readOnlyHint=true and destructiveHint=false. It also adds useful behavioral context beyond the annotations by enumerating the specific failure modes it recognizes, such as CrashLoopBackOff, ImagePullBackOff, and Services without endpoints.

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

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

Three sentences carry unusual density without filler: behavior, recognized failure modes, and the trigger condition. Every clause adds information an agent needs, and the description is front-loaded with the core diagnostic purpose before the mode list.

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

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

The description covers the output behavior, the common failure signatures, and the exact condition for invocation. The only notable gap is parameter guidance, but with optional parameters, a null default, and an output schema present, the tool is still largely safe to invoke. The description could add a sentence defining what `names` and `namespace` scope the diagnosis to, but the current level of context is useful.

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

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

The schema description coverage is 0%, and the description does not compensate for it: it never explains what `names` or `namespace` mean, what they can be omitted, or how they scope the diagnosis. An agent can infer that `namespace` is likely a Kubernetes namespace, but `names` is ambiguous and the default-null behavior is not described.

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

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

The description names a specific verb and resource: it gathers pods, container states, Services, and events, then produces a diagnosis. It clearly distinguishes itself from lower-level siblings like get_pods or get_deployment_status by describing its synthesis of evidence into a diagnosis, not just a raw listing.

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

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

It gives an explicit trigger condition: 'Call this whenever verify_deployment reports healthy=false.' This decisively tells the agent when to invoke this tool instead of relying on the raw get_* siblings, and the reference to verify_deployment ties it to the verification workflow.

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 idempotentHint=true and destructiveHint=false, and the description adds meaningful behavioral context: it writes only needed resources, uses placeholders for secrets, and never touches a cluster. It doesn't explicitly state idempotency, but the annotations cover that; the description adds value by explaining the placeholder behavior and the file-only side effect.

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 dense paragraph that front-loads the core action and then adds resource-type details and constraints. It is efficient, but the middle sentence listing resource types is somewhat long; still, every sentence earns its place by clarifying behavior.

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 are covered elsewhere. The description covers the main side effects, the secret placeholder behavior, and the relationship to create_migration_plan. The main gap is that several parameters (path, output_dir, ingress_host, include_ingress) are not explained, but the overall behavior is clear enough for an agent 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 0%, so the description must compensate. It mentions namespace and image_registry explicitly and explains their relationship to create_migration_plan, but it does not explain path, output_dir, ingress_host, or include_ingress. The description adds some meaning for two of six parameters, but the rest remain undocumented in both schema and description.

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

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

The description clearly states the tool writes Kubernetes YAML for a project into a per-project directory under generated/, and distinguishes it from cluster-touching operations by explicitly saying it writes files only. It also names the sibling create_migration_plan, which helps differentiate it from related planning 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 says to pass the same namespace/image_registry used in create_migration_plan, and notes that the plan is re-derived from the project. It also clarifies that it does not touch a cluster, which tells the agent when not to use it (e.g., when the goal is to apply manifests, use apply_manifests 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?

The annotations already establish that this is a non-destructive, read-only, idempotent operation. The description adds that it lists nodes and namespaces and frames the reachability check in a way that helps the agent interpret potential failures. This goes beyond what the annotations alone convey.

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

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

Two compact sentences with no filler. The primary behavior is front-loaded, and the second sentence provides actionable usage context that 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-parameter reachability check with strong safety annotationscarset, nothing essential is missing. The description tells the agent what to expect and when to call it; no output schema is present, but the simple list/confirm behavior is sufficiently clear.

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?

This tool takes zero parameters鑑with full schema coverage by default. The description doesn't need to explain parameter semantics, and it doesn't try. A baseline of 4 is appropriate for a parameterless tool.

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

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

The description uses a specific verb ('Confirm', 'list') and names the exact resources ('nodes and namespaces'). It clearly distinguishes this from the sibling deployment and inspection tools by focusing on cluster connectivity rather than project or manifest 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 explicitly says 'Call this before deploying', giving clear situational guidance. It does not name alternatives or state when not to use it, so it stops short of the strongest possible guidance, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description goes beyond annotations by explaining the fallback behavior from Deployment to StatefulSet and the specific status dimensions reported, which adds valuable behavioral context.

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

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

A single, tightly worded sentence front-loads the core action and result, then adds the fallback behavior. Every phrase contributes meaning and there is no filler.

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

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

With an output schema present and annotations covering safety, the description covers the main behavioral nuance (Deployment-to-StatefulSet fallback). The only notable gap is parameter semantics, particularly the optional namespace, but overall the definition is sufficiently complete for a read-only status 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 0%, so the description must compensate, but it does not explain 'name' or 'namespace' beyond implying the name refers to a Deployment/StatefulSet. The 'same name' phrasing gives partial meaning to 'name', but 'namespace' remains entirely undocumented.

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

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

The description uses a specific verb ('report') and resource ('Deployment', with StatefulSet fallback) and names the exact information returned: desired vs ready replicas and rollout conditions. This clearly separates it from generic status or pod-level sibling tools.

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

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

There is no guidance on when to prefer this tool over closely related siblings like verify_deployment, diagnose_deployment, or get_pods. The StatefulSet fallback is a behavioral detail, not usage guidance, so the agent is left to infer the right context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds useful behavioral context: events are recent and returned oldest first. It also explains the kind of content the caller should expect in the events. No description-annotation 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?

Two sentences; the first delivers the core action and ordering, the second supplies diagnostic context. No filler or repetition, and the most decision-relevant information is front-loaded.

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

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

The combination of read-only annotations, an output schema, and a clear use-case sentence covers the core invocation decision. However, the missing parameter semantics for limit and namespace means an agent must guess filter behavior, so the definition is not fully complete.

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

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

Schema coverage is 0%, so the description needed to explain limit and namespace, but it never mentions either parameter. Names and defaults are inferable, but behavior like namespace=null meaning all namespaces or limit truncating the returned list is absent. This is the definition's main gap.

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

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

The description opens with a direct action ('Return ... events'), names the resource type (Kubernetes events), and specifies ordering ('oldest first'). The diagnostic use cases distinguish it from pod-status tools like get_pods, so the purpose is unambiguous.

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

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

The second sentence explicitly ties the tool to event-driven failure modes (scheduling, image pull, probe, volume) that 'pod status alone does not' explain. This gives the agent a clear trigger condition and implies the alternative is to check pod status first. It doesn't name a specific sibling tool, so it falls just short of a fully explicit routing rule.

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, and non-destructive behavior. The description adds useful behavioral context beyond annotations by explaining that `previous=true` reads logs from the already-died instance and that this is where the real error will be found. This is valuable operational nuance not present in the schema.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the most valuable operational hint about crash-looping is included efficiently. 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 log-fetching tool, this is largely complete: annotations cover safety, an output schema exists, and the description adds the key crash-loop guidance. Minor gaps remain around container selection and tail behavior, but these are either self-evident from the schema or low-risk defaults.

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

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

The schema has 0% description coverage, so the description must compensate. It meaningfully explains the `previous` parameter's purpose in crash-loop scenarios and implies the `container` parameter via 'container logs.' However, it does not clarify `namespace`, `tail_lines`, or multi-container behavior, leaving those to inference from parameter names and defaults.

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: 'Read a pod's container logs.' This clearly distinguishes the tool from siblings like get_pods, get_events, and get_deployment_status, making the purpose immediately identifiable.

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

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

The description provides a clear scenario for using the `previous` parameter with a crash-looping pod, which is actionable guidance. It doesn't explicitly name alternative tools or state when not to use it, but the purpose is obvious enough that an agent can infer the appropriate use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description only needs supplementary behavioral context. It adds that the tool surfaces restart counts and detected problems like CrashLoopBackOff and ImagePullBackOff, which is useful beyond the schema. There is no contradiction with 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 one compact, front-loaded sentence with returned fields, followed by a short usage directive. Every sentence earns its place and there is no filler or repetition of annotation data.

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 output schema covers the return shape, annotations cover the safety profile, and optional parameters keep the call simple. The description gives a clear diagnostic purpose and relevant problem categories; it only lacks explicit guidance on namespace/selector semantics, which keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description should compensate by explaining namespace and selector behavior. It does not mention either parameter or any default filtering semantics. An agent must rely on Kubernetes conventions or infer from the property names alone, which is a meaningful gap.

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

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

The description gives a specific verb ('List'), a clear resource ('pods'), and enumerates the returned fields (phase, ready count, restart count, detected problem). It also names concrete problem categories and distinguishes itself as the first check when a deployment looks unhealthy, setting it apart from the sibling log/status 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?

It explicitly says 'Use this first when a deployment looks unhealthy', giving a direct trigger condition for when to choose this tool. It does not list when-not-to-use or alternatives such as get_deployment_status, but the stated condition is actionable and sufficient for initial selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds interpretive context beyond the schema and annotations—that zero endpoints explain unreachable apps—which helps an agent reason about the result. No contradictions with annotations.

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

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

Two sentences with no filler; the output fields are front-loaded in the first sentence and the diagnostic insight in the second. Every word earns its place.

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

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

For a simple read-only listing tool with an output schema and full annotation coverage, the description conveys the core purpose and a useful diagnostic mental model. The only notable omissions are parameter default semantics and explicit guidance about namespace scope, which prevent a perfect score.

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

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

Schema description coverage is 0% and the description does not mention the 'name' or 'namespace' parameters at all. While the parameter names are self-explanatory, the null/default behavior (e.g., whether null namespace means 'all namespaces' or 'current namespace') is left unspecified, which is a real gap for correct invocation.

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 ('List'), a resource ('Services'), and the exact fields returned ('type, ports, selector and endpoint count'). This clearly separates it from sibling tools like get_pods and get_events, which target different resource types, so an agent can select it confidently.

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

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

There is no explicit when-to-use or alternative routing, but the second sentence provides a clear diagnostic trigger: check services when an application is unreachable even though pods look healthy, because zero endpoints are a common cause. That is useful context, though it stops short of naming sibling alternatives or 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 cover the read-only, idempotent, non-destructive nature of the tool. The description adds valuable behavioral detail beyond that: it normalises the parsed services and redacts credential-looking values, listing them by key in secret_keys. This gives the agent important expectations about safety and output shape.

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

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

The description is a single dense sentence with the core action front-loaded and the extracted fields presented in a compact, scannable list. There is no filler, no repetition of the name, and every part adds information an agent can use.

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 readOnlyHint, idempotentHint, destructiveHint, and an output schema provided, the description only needs to explain the tool's scope and notable behaviors such as redaction. It does that clearly, so the agent has enough information 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?

There is only one parameter, path, and the schema has no description for it. The tool description implies that path refers to a Compose file, but it does not specify path format, accepted extensions, or whether directories are supported. The meaning is partially compensated by the clear purpose, but not fully.

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: 'Parse a Compose file into normalised services' and enumerates exactly what will be extracted. This clearly distinguishes it from sibling tools like inspect_dockerfile and inspect_environment without requiring the agent to open schemas.

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

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

The Compose-specific wording gives clear context for when to use this tool: whenever a docker-compose file needs to be parsed or inspected. It does not explicitly name alternative tools or state when not to use it, but the target is unambiguous enough to route an agent correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by disclosing what the parser extracts and clarifying that EXPOSE ports reflect the actual listening port — behavior an agent would not know from annotations alone. It does not contradict the safety profile.

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

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

Two sentences, zero fluff. The first sentence front-loads the purpose and enumerates the extracted facts; the second provides a practical usage example. Every word earns its place, and the structure supports quick agent comprehension.

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

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

The tool is simple (1 parameter, read-only, idempotent) and an output schema is present, so the description does not need to explain return values. It covers what the tool does, what facts it extracts, and when to use it. The only completeness gap is the underspecified 'path' parameter, which is minor given the tool's simplicity.

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

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

With schema description coverage at 0% and only one parameter ('path'), the description carries the burden of explaining the parameter. It implies that 'path' points to a Dockerfile (via 'Parse a Dockerfile' and the tool name), but it never explicitly defines the expected format, whether a directory is accepted, or if the path is local/remote. The meaning is inferable but not fully specified.

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

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

The description names the specific verb 'Parse' and the resource 'Dockerfile', then enumerates the exact facts returned (base images, build stages, EXPOSE ports, WORKDIR, USER, ENTRYPOINT/CMD, ENV keys, HEALTHCHECK). It clearly differentiates from sibling tools like inspect_compose and inspect_project by defining the Dockerfile-specific scope and even provides a concrete use case ('learn which port an image actually listens on').

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

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

The description gives clear context: use this tool when you need Dockerfile facts for a migration, and specifically to determine the actual listening port. It does not explicitly name sibling tools as alternatives, nor does it state when not to use it, so it falls short of a 5 but is well above providing no 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?

The description explicitly states that secret VALUES are never returned, only key names, and that it is safe to call on projects with real credentials. This adds meaningful behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining the safety guarantee in concrete terms.

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

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

Two sentences with no filler. The core function is stated first, followed by the critical safety guarantee. Every word earns its place.

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

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

The tool has an output schema, so return values are documented elsewhere. The description covers the key behavioral guarantee (no secret values returned) and the data sources (.env files, Compose). It doesn't mention edge cases like missing .env files or how classification works, but for a read-only inspection tool with an output schema, 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?

Schema description coverage is 0%, so the description must compensate. It explains what the tool does with the path (inspects .env files and Compose), but doesn't specify path format, whether it accepts file or directory paths, or what happens if the path is invalid. The single parameter is simple enough that the description provides adequate context, but not detailed semantics.

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

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

The description clearly states the tool lists environment variables from .env files and Compose, and classifies them as configuration or secret. This is a specific verb-resource combination that distinguishes it from sibling tools like inspect_project or inspect_compose.

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

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

The description implies when to use it: when you need to know which environment variables a project uses and their classification. It doesn't explicitly name alternatives or exclusions, but the context of sibling tools like inspect_project and inspect_compose makes the use case 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, idempotentHint, and non-destructive behavior, lowering the bar. The description adds a meaningful behavioral guarantee: 'Secret values are never returned,' and clearly scopes what artefacts are reported. Nothing contradicts 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 compact, front-loaded with 'Start here,' then provides a precise artefact list and a security caveat. Every sentence earns its place; there is no filler or redundant restatement of the title.

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-only inspection tool with an output schema and safety annotations, the description covers the key facts: what the tool reports, what path it expects, and the secrets-handling behavior. Nothing critical is missing for an agent to select and 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 0%, so the description must compensate. It does so by defining the path as a 'project directory,' which is more informative than the bare schema title 'Path.' It does not specify path format or accessibility, but for a single obvious parameter this is adequate.

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

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

The description uses a specific verb-resource pair and clearly defines the tool's scope: 'report which Docker artefacts it contains.' Enumerating Dockerfile(s), Compose file, .env files, source directories, dependency files, and Compose service names distinguishes it from siblings like inspect_dockerfile and inspect_compose, which presumably inspect individual artefacts in detail.

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 opening phrase 'Start here' explicitly positions this tool as the entry point, and the artefact list maps naturally to sibling inspection tools, implying this is the discovery step before deeper inspection. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond these by revealing that the tool catches mistakes that survive kubectl apply, and by stating the return behavior: 'Returns valid=false with human-readable errors when the manifests would break.' This gives the agent an accurate mental model of what happens when the tool runs.

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

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

The description is front-loaded with the core purpose and followed by a clear usage directive and return-value note. The long enumeration of validation categories is verbose but earns its place by communicating the tool's full scope. Every sentence adds value, though a bit of tightening would be possible.

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 only one parameter, an output schema present, and annotations covering the safety profile, the description supplies everything an agent needs: what it validates, when to run it, and what a failure returns. No critical selection or invocation information 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 schema has one required 'path' parameter with 0% description coverage, so the description must compensate. It implies path refers to the manifests being checked, but never explicitly states whether it should be a file, directory, or repository-local path. The tool's title and purpose make the parameter inferable, but the exact accepted format remains a gap.

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

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

The description opens with a specific verb ('Check') and resource ('manifests'), then enumerates concrete failure classes such as selectors matching no pods, Service targetPort mismatches, and missing ConfigMap/Secret/PVC references. This makes the tool's purpose unmistakable and clearly distinguishes it from sibling tools like generate_manifests, apply_manifests, and verify_deployment.

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

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

The description explicitly instructs 'ALWAYS run this before deploying', giving a clear and strong when-to-use directive. It does not explicitly list when-not-to-use scenarios or alternative tools, so it falls just short of a perfect score, but the pre-deployment context is unambiguous.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: the specific checks performed, health-check proxying, and the existence of a 'healthy' boolean result. There is no contradiction with annotations.

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

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

The description is dense but efficient: the core behavior is front-loaded, each clause adds a distinct check, and the routing instruction earns its place. No redundant or filler content.

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

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

The description covers purpose, behavior, output signal, and escalation, and an output schema exists to handle return details. The only notable gap is the meaning and selection semantics of names and namespace, which keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies health_path ('health endpoint responds through the API server proxy') but does not explain how names or namespace select workloads, nor what null defaults mean. This is a meaningful gap for optional parameters.

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

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

The description names a specific verb and resource: 'Run the post-deployment checks in one call' and enumerates exactly which checks are performed. It also implicitly differentiates this aggregated verification tool from the individual sibling status tools like get_pods and get_services.

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

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

Explicit guidance is given: 'Never assume a deployment succeeded -- call this.' It also names the escalation path: 'If healthy is false, call diagnose_deployment.' This tells the agent when to invoke this tool versus alternatives.

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