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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the human-minted token requirement and the constraint that the action must have been previously proposed, providing context beyond the annotation flags. 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?

One concise summary sentence followed by a compact Args block. Every sentence earns its place – no filler, clear front-loading, 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?

With only 2 params and an output schema present, the description covers the essential workflow, parameter provenance, and human approval requirement. However, it does not state whether applying is synchronous or idempotent, which would be useful for a destructive action.

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%, but the description fully explains both parameters: proposal_id is 'id returned by propose_cluster_action' and approval_token is 'token the operator produced with ocm-mcp approve <id>'. This adds meaningful operational meaning beyond the bare schema types and 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 opens with 'Apply a previously proposed cluster lifecycle action' – a specific verb ('apply'), specific resource ('cluster lifecycle action'), and scope ('previously proposed'). It clearly distinguishes itself from the sibling propose_cluster_action by indicating this tool executes an already-proposed action.

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 states prerequisites explicitly: requires a human-minted token, proposal_id from propose_cluster_action, and approval_token from 'ocm-mcp approve <id>'. This gives clear context that the tool is used after proposal creation, though it does not explicitly list when not to use it or name alternative tools.

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

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

The description adds the approval token requirement and the two-step process, which goes beyond the annotations. It does not restate the destructive hint, but the annotations already cover that; the added token context is valuable.

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

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

The description is concise and well-structured. The main action is front-loaded, and the Args section is brief, with no 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?

The description provides complete invocation context: required token, parameter sources, and step relationship to propose_manifestwork. With an output schema present, the description does not need to explain return values.

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 0% schema description coverage, the description fully explains both parameters, including their origins: proposal_id from propose_manifestwork and approval_token from `ocm-mcp approve <id>`. This is essential 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 clearly states 'Apply a previously proposed ManifestWork', with a specific verb and resource. It distinguishes itself from siblings like propose_manifestwork and rollback_manifestwork by the 'previously proposed' qualifier and the mention of an approval token.

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

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

The description implies the tool is used as the second step after propose_manifestwork, referencing that proposal_id comes from that function. It does not explicitly name alternatives or exclusions, but the 'previously proposed' phrasing provides clear usage context.

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

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

Annotations already establish read-only, non-destructive behavior, so the bar is lower. The description adds the specific resource type (ManagedClusterAddOn) and the statuses (Available/Degraded) but does not disclose additional behavioral traits such as whether it returns all add-ons or only degraded ones, pagination, or any special authorization needs.

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

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

The description is a single, front-loaded sentence that states the scope and resource without redundancy. Every word contributes meaning, and it fits on one line.

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

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

For a zero-parameter, read-only tool with an existing output schema, the description provides sufficient context to understand the tool's purpose and scope. It could have been more explicit about how it relates to sibling health tools, but it is complete for 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?

The tool has zero parameters, and the schema confirms this with 100% coverage. Since there are no positional or named arguments to explain, the description does not need to compensate. The baseline for parameterless tools is met.

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 resource (ManagedClusterAddOn health) and the scope (per-cluster, across the fleet), distinguishing it from sibling tools like get_cluster_health and get_fleet_health. It states the object being evaluated and the key statuses observed.

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

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

The description implies the tool is for checking add-on health across clusters, but it does not explicitly state when to prefer it over alternatives or provide exclusionary guidance (e.g., 'for cluster-level health use get_cluster_health'). The use case is evident from the resource name but not explicitly contrasted.

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 and destructiveHint=false, so no additional safety disclosure is needed. The description adds useful behavioral context beyond the annotations: it clarifies the audit log is server-local, describes what the log contains (inspected, proposed, approved, and applied actions), and explains the default count of entries.

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 extremely concise and front-loaded with the core purpose. The parameter explanation and use case follow naturally, and every sentence adds value without 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?

Given the simple tool structure (one optional parameter, output schema present), the description fully covers what the agent needs: purpose, parameter semantics, and a concrete usage scenario. It is complete and self-sufficient.

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

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

The input schema has 0% description coverage, so the description carries full burden for parameter documentation. It explicitly explains 'last_n' as the number of trailing audit entries to return and states the default of 30, perfectly compensating for the schema 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 clearly states the tool returns the last N entries of the server's own tool-call audit log. This is a specific verb+resource+scope, and no sibling tool provides audit functionality, so it is fully distinguished from alternatives.

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 recommends using this tool at the end of an incident to write an accurate post-incident report, providing clear context for when to use it. It does not mention when not to use it or name alternatives, but the context is unambiguous given the unique audit purpose.

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 this as read-only and non-destructive. The description adds meaningful behavioral details: it returns specific fields and clarifies that the cluster name must be 'as the hub knows it'. It does not mention error handling or prerequisites, but the annotation coverage lowers the bar.

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

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

The description is compact and well-structured with distinct summary, Args, and Returns sections. Every sentence earns its place, and there is no redundant filler or technical jargon.

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

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

For a single-parameter read tool with an output schema, this description covers the operation, parameter semantics, and returned fields. It lacks explicit comparisons to sibling tools, but the low complexity and rich annotations make it sufficiently complete.

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

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

The schema only provides a title 'Cluster' with no description, so the description must compensate. It does so by explaining the parameter as 'managed cluster name as the hub knows it' and directing users to list_clusters for valid names, adding critical meaning beyond the schema.

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

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

The description opens with 'Full view of one ManagedCluster', clearly stating the verb and singular resource. It enumerates the returned data (acceptance, taints, hub conditions, Kubernetes version, capacity, ClusterClaims), distinguishing it from siblings like list_clusters and get_cluster_info.

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 tells users to get the cluster name from list_clusters, providing a useful pointer for the required argument. However, it does not explicitly state when to prefer this over alternative get_* tools or provide exclusion criteria, so usage guidance is mostly implied.

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

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

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false. The description adds meaningful behavior: the availability of pod/deployment details depends on the spoke context, which is not captured in annotations. This explains a conditional aspect of the output. No contradiction.

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

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

The description is brief and front-loaded with the core purpose, followed by a structured 'Args' block. Every sentence adds necessary information without redundancy, achieving high conciseness with clear structure.

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

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

Given the presence of an output schema, the description doesn't need to explain return structure. It covers the tool's scope, the meaning of 'cluster', and a critical prerequisite. It could be slightly more explicit about how the response differs when the spoke context is missing, but it does mention the distinction, so completeness is good.

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 must clarify the parameter. It does: 'cluster: managed cluster name' and further relates it to the spoke context requirement for pod/deployment details. This gives the single parameter both a clear semantic and a behavioral implication beyond the schema.

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

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

The description states a clear, specific purpose: 'Health summary for one cluster' and enumerates the key components (hub conditions, unhealthy pods, degraded deployments). This distinguishes it from sibling tools like get_cluster_info, get_fleet_health, and get_addon_health, which target different scopes or 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?

It explicitly states a prerequisite: pod/deployment detail requires a read-only spoke context (OCM_MCP_SPOKE_CONTEXTS), while hub conditions work without one. This provides clear context for when the tool can be used fully, but it does not name alternative tools for when not to use it.

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

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

The description adds valuable behavioral context beyond the annotations: it reads ManagedClusterInfo on the hub, needs no spoke access, and reports clearly if the add-on is missing. Even though readOnlyHint=true is already given, the source-of-truth detail and error behavior enrich transparency.

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

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

The description is compact and well-structured: a lead sentence with outcomes, then an Args block, then context. No redundant sentences; every line adds information about scope, requirements, or 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?

Given the tool's simplicity (one parameter) and that an output schema exists, the description is complete. It covers prerequisites (add-on), scope (any spoke, hub-read), and error behavior, leaving no significant gaps for the agent to guess.

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%, the description compensates fully by documenting the sole parameter: 'cluster: managed cluster name.' This adds clear meaning that the input schema lacks, making the parameter unambiguous.

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 with specific content: 'Extended inventory for one cluster from the hub: OpenShift version, nodes, console URL.' It uses a specific resource and scope, distinguishing it from sibling tools like get_cluster by emphasizing 'extended' inventory and the hub-source.

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 usage context: it reads from the hub, works for any spoke (external OpenShift, HCP, cloud), and requires the ACM/MCE add-on. It explains when the tool can be used but does not explicitly name alternative tools or state when not to use it.

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

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

Beyond the readOnly/destructive annotations, it discloses concurrent scans, error entries for broken spokes, and ordering by problem severity. This adds meaningful behavioral context not present in the schema or annotations.

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

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

The description is well-structured with a clear opening sentence, an Args section, and behavioral notes. Every sentence adds value, and the content is front-loaded with the core purpose.

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

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

Given the simple single-parameter schema, presence of an output schema, and read-only annotations, the description covers all necessary aspects: scope, error behavior, ordering, and alternative tool choice. Nothing essential is missing.

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

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

The only parameter (clusters) has zero schema description, but the tool description fully explains it as an optional comma-separated list of cluster names, with empty meaning all clusters. This fully compensates for the schema 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 explicitly states the tool's purpose: health of the entire fleet in one call, covering hub conditions and spoke scans. It clearly differentiates from the sibling get_cluster_health by recommending this over looping that 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?

Directly provides usage guidance: 'Prefer this over calling get_cluster_health in a loop.' Also implies when to use (whole fleet vs single cluster) and describes the optional scope 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 annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds context about what data is returned (version, conditions, NodePools), but does not disclose other behaviors like permission requirements or response limitations. This adds some value beyond annotations without contradicting them.

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

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

The description is very concise, front-loaded with the key resource and output fields, and includes a clean Args section. Every sentence contributes useful information without unnecessary 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 available, return structure is already covered. The two parameters are well documented. The only notable gap is the lack of usage context, but for a simple get-by-key tool this is acceptable and the description is sufficiently complete 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?

Both parameters are explained: name as the HostedCluster name, and namespace as the hosting namespace. This adds meaning beyond the schema's minimal type-only definitions. Given schema description coverage is 0%, this is essential and effectively compensates for the 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 states that the tool provides detailed HostedCluster information including version, conditions, and NodePools. Although it lacks an explicit verb, the tool name 'get_hosted_cluster' clarifies the action. It is distinguishable from sibling tools like list_hosted_clusters and get_cluster.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or comparisons to other getter tools, leaving the agent to infer usage context.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds that it reads conditions and per-resource feedback reported from the spoke, which clarifies the data source and behavior. It does not contradict 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, with a summary line, args list, and use-case sentence. It is well-structured but slightly redundant in mentioning status feedback twice.

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 simple two-parameter read-only tool with an output schema, the description covers purpose, usage, and parameter semantics adequately. It is 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?

With 0% schema description coverage, the description provides the necessary meaning for both parameters: cluster is the managed cluster name and name is the ManifestWork name. This fully compensates for the missing schema documentation, though it adds no extra constraints.

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 provides detailed ManifestWork status including top-level conditions and per-resource feedback. It distinguishes from sibling list/manipulation tools by focusing on a single ManifestWork's status.

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

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

It explicitly says to use this tool to answer why a ManifestWork is not Applied/Available and to read status feedback such as replica counts. However, it does not explicitly name alternative tools for listing or creating, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's word 'reads' aligns with these. The description adds context by specifying that it reads the PlacementDecisions subresource, which clarifies the exact data source. This is a useful behavioral disclosure beyond the annotations, with no contradictions.

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 extremely concise: one purpose sentence plus a compact parameter list. Every word earns its place, and the core purpose is front-loaded. There is no redundancy or extraneous 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?

For a tool with only two required string parameters, no nested objects, an output schema, and read-only annotations, the description provides adequate context. It covers the tool's purpose and both parameters, while the output schema handles return values. It could mention error behavior (e.g., placement not found), but this is a minor gap for such a simple read operation.

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

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

The input schema provides no descriptions (0% coverage), so the description's Args section is critical. It explains both parameters: 'placement: Placement name' and 'namespace: the namespace the Placement lives in.' These are clear and sufficient, fully compensating for the schema's lack of detail.

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 'Which clusters a Placement actually selected (reads its PlacementDecisions)', which clearly states the tool's function using a specific verb ('reads') and a specific resource ('PlacementDecisions'). This distinguishes it from sibling tools like list_placements, which list placements rather than their selected clusters.

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

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

The description strongly implies when to use this tool: when you need to know the clusters a specific Placement selected. It does not explicitly name alternatives or state when not to use, but the context is clear from the purpose statement alone, especially given the sibling tool list.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds a non-obvious behavior: falls back to the previous container instance if the current one is crashing. It also explains the empty container default, which adds practical context not captured by the schema.

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

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

The description is efficient: a one-sentence purpose, a compact Args block, and a single behavioral note. Every line earns its place with 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?

With an output schema present, return values are covered elsewhere. The description covers the tool's core behavior, parameters, and the distinctive fallback behavior. It doesn't mention permissions or rate limits, but annotations provide safety context, so the coverage is nearly complete.

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

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

With 0% schema description coverage, the description lists all five parameters with brief but useful semantics: cluster is a managed cluster name, container empty picks the default, lines sets the trailing count. This compensates well for the missing schema descriptions, though some parameters (e.g., pod, namespace) only restate their names.

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 ('Tail') and resource ('logs from a pod on a managed cluster'), clearly distinguishing it from sibling tools like get_resource or query_events. The purpose is immediately clear 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?

The description implies usage by defining the exact context (cluster, namespace, pod), but does not explicitly name alternatives or exclusions. It provides enough context for an agent to infer when to use it, but lacks explicit 'when to use vs. not' guidance.

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

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

Beyond the annotations (readOnlyHint, non-destructive, openWorldHint), the description discloses critical behavioral traits: 'in full' (returns the complete resource), 'allow-listed' (scope restriction), and especially the strong statement that Secrets are not retrievable because the capability 'does not exist rather than being merely restricted'. This adds significant context about the tool's guarantees and limitations.

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 succinct and well-structured. The opening sentence states the purpose immediately, followed by a compact args list, and a final note on an important security limitation. Every sentence earns its place with no 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 generic nature and the presence of an output schema (which presumably documents the return shape), the description covers essential aspects: scope (allow-list), single-resource retrieval, namespace condition, and the Secrets exclusion. It provides sufficient context for an agent to decide when and how to invoke the tool correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter: resource (type and allow-list reference), name (object name), and namespace (required for namespaced types). This adds meaning beyond the schema's property names and types, making the parameters self-explanatory.

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 'Generic get of one allow-listed OCM resource, in full' with a specific verb ('get'), resource ('OCM resource'), and scope ('allow-listed', 'one'). It distinguishes itself from the many specific getter tools (e.g., get_cluster) by emphasizing its generic nature and references the allow-list, making the tool's purpose unambiguous.

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

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

The description provides clear context: it is a generic getter for allow-listed resources, and the namespace requirement for namespaced types is specified. It also notes that Secrets are excluded, which is a key limitation. However, it does not explicitly state when to prefer this over specific getter tools or list_resources, leaving the alternative selection implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds a useful nuance: that scores reside in the hub namespace of the managed cluster. It does not go beyond this, but given the strong annotations, this is adequate.

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

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

The description is compact and front-loaded with the primary purpose, followed by a brief clarification of the namespace. The Args section is minimal and adds necessary semantic detail 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?

For a simple read-only list operation with one parameter and an existing output schema, the description covers purpose, parameter semantics, and relevant namespace context. It is sufficiently complete without over-explaining.

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 provides meaningful context for the 'cluster' parameter beyond the schema, explaining that it is a 'managed cluster name' and that its hub namespace holds the scores. This fully compensates for the 0% schema description coverage.

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

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

The description clearly states the tool's action: 'List AddOnPlacementScores in a cluster's namespace.' It identifies the specific resource (AddOnPlacementScores), the location (cluster's namespace/hub namespace), and provides context ('custom scores prioritizers consume'), distinguishing it from sibling tools like list_addons_for_cluster.

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 a use case by explaining that these scores are consumed by prioritizers, hinting at when this tool would be relevant. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or when not to use it.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the health context and the underlying ManagedClusterAddOn resource, but does not go beyond that. It does not contradict 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 extremely concise: a single sentence conveying purpose and an args list. Every word earns its place, and the structure is clean and 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?

Given the tool's simplicity, one parameter, read-only annotations, and an output schema, the description is adequate. It explains the return includes health and the underlying resource, which is enough 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?

With zero schema description coverage, the description clarifies that 'cluster' is a managed cluster name, adding meaning beyond the schema's title. Although minimal, it suffices for a single string 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 states the tool lists every add-on installed on a specific cluster with health, using a specific verb and resource scope. It distinguishes itself from sibling tools like list_cluster_management_addons by scoping to a single cluster.

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

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

The description clearly implies when to use the tool (when you need all add-ons for a cluster) and the scope is obvious. However, it does not explicitly mention alternatives or exclusions, 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 cover read-only and non-destructive behavior. The description adds useful context: the data is rolled up from status, indicating a data source and aggregation behavior. It does not disclose performance traits, ordering, or error scenarios, but given the readOnlyHint, this is acceptable.

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 concise sentence, front-loaded with the resource and scope, and contains no filler. It efficiently conveys the purpose and the returned fields.

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

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

Given the tool has no parameters, a readOnlyHint, an output schema, and a clearly described purpose, the description is sufficient for a simple listing tool. It lacks details on ordering or list size, but these are unlikely to be critical for this straightforward operation.

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

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

The tool has zero parameters and the schema coverage is 100% (empty schema), so there is nothing to explain. Description correctly does not add param details. Baseline for 0 params is 4, and no deduction is warranted.

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 verb (list/retrieve) and the resource (ClusterClaims for every cluster), with specific fields (id, platform, region, version). It distinguishes from sibling tools like list_clusters or get_cluster by focusing on the rolled-up ClusterClaims view.

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

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

The phrase 'Every cluster's... rolled up from status' implies this is for a fleet-wide, aggregated view of claims, not per-cluster detail. However, it does not explicitly contrast with alternatives or state when to use this tool over list_clusters or get_cluster, so guidance remains implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which are consistent with the read-only 'List' verb. The description adds the fleet-level scope and mentions the install strategy as part of the returned information, but it does not describe return format, pagination, or any additional behavioral nuances. Since annotations cover the safety profile, the description adds modest 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?

The description is a single sentence of 12 words, front-loaded with the verb and resource, and contains no redundant or filler content. It is appropriately sized for the tool's simplicity.

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 no-parameter list tool with an output schema and read-only annotations, the description sufficiently covers purpose and scope. It identifies what is listed and the fleet-level domain; the output schema handles return value details, so no further explanation is needed.

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

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

The input schema is empty with zero parameters, so there are no parameter semantics to clarify. Per the baseline rules for 0 parameters, a score of 4 is appropriate; the description does not need to compensate for undocumented 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 uses the specific verb 'List' and clearly identifies the resource as 'fleet-level add-on definitions (ClusterManagementAddOn)', including the technical type name and the fleet-level scope. This distinguishes it from sibling tools like list_addons_for_cluster which target cluster-level add-ons.

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

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

The description implies usage for fleet-level add-on definitions, but it does not explicitly state when to use this tool versus cluster-level alternatives or list any exclusions. There is no mention of alternatives or scenarios where another tool should be preferred, so guidance is only implied by the resource name and scope.

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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the fields included in the listing (availability, version, labels, capacity) and the 'all' scope, which goes beyond the annotations. No contradiction exists.

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

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

A single, front-loaded sentence conveys the action, scope, and output fields with no filler. 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?

Given the absence of parameters, the presence of an output schema, and the readOnly annotation, the description is complete for a list-all tool. It clearly names the resource type and the fields of interest, and the sibling context shows it is distinct from list operations on claims, sets, and other cluster-related entities.

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 per the rubric the baseline is 4. The description correctly avoids inventing parameter details and the schema has no properties to elaborate on.

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 'List' with the resource 'managed clusters' and enumerates the returned fields (availability, version, labels, capacity). It clearly distinguishes itself from sibling tools like get_cluster (which fetches a single cluster) and list_cluster_claims/list_cluster_sets (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 phrase 'all managed clusters' establishes the tool's scope as a broad listing operation, implying use when an aggregate view is needed rather than a single-cluster lookup. However, it does not explicitly mention alternatives such as get_cluster for detailed views or note when not to use this tool, so it stops short of full 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 indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral context about the namespace argument (empty lists bindings across all namespaces), which is not present in the schema. No additional behavioral caveats are needed for a simple list operation.

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 parts: a one-sentence purpose and a brief args section. Every word earns its place; no redundancy or fluff. It is appropriately sized for the tool's simplicity.

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 a single optional parameter, annotations cover safety, and an output schema exists. The description provides the essential purpose and parameter semantics, making it complete for an AI agent to select and invoke correctly. No gaps for this simple read-only list operation.

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

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

The input schema has zero description coverage for the 'namespace' parameter. The description fully compensates by explaining 'limit to one namespace; empty lists bindings across all namespaces', giving clear semantics for the only 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 states the action 'List ManagedClusterSetBindings' and provides a parenthetical explaining what these bindings represent ('which ClusterSets a namespace's Placements may use'). This is a specific verb+resource and distinguishes from sibling tools like list_cluster_sets or list_placements.

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

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

The description implies usage: you call this to find which ClusterSets are available to a namespace's Placements. It also explains the namespace parameter behavior (empty for all namespaces), but it does not explicitly mention alternatives or when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the return content (selector type and member clusters) but does not disclose additional behaviors like pagination, ordering, or potential filtering. 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?

A single, concise sentence that fully conveys the tool's purpose and key output. 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?

For a zero-parameter list tool with a read-only annotation and an output schema, the description provides sufficient context. It names the resource and the specific attributes returned, making the tool's behavior 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?

The tool has zero parameters, so the schema provides full coverage. The baseline for no parameters is 4, and the description does not need to add param semantics. The mention of return content is relevant context.

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 the action ('List'), the resource ('ManagedClusterSets'), and the specific information returned ('with their selector type and member clusters'). This clearly distinguishes it from sibling tools like list_clusters or list_cluster_set_bindings.

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

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

The description implies usage for listing ManagedClusterSets but does not explicitly state when to use this tool versus alternatives such as list_cluster_set_bindings or list_clusters. No exclusions or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds important behavioral context: HostedCluster objects live on the control-plane-hosting cluster, and if hosted elsewhere, 'this reports that clearly.' While the exact reporting behavior is vague, it does disclose a key limitation beyond the annotations. The namespace semantics are also disclosed.

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

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

The description is concise and well-structured: a one-sentence purpose, a parameter note, and a context paragraph explaining edge cases. Every sentence adds value, though the phrase 'this reports that clearly' is slightly vague and could be expanded or removed without loss of conciseness.

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 list tool with one parameter, an output schema, and read-only annotations, the description covers the tool's purpose, usage condition, parameter semantics, and the key edge case of remote management clusters. It is complete enough 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 0%, so the description carries the full burden for the only parameter. The 'Args' section explicitly states 'namespace: limit to one namespace; empty lists across all namespaces,' giving clear meaning beyond the schema's default value. This fully compensates for the missing schema 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 states 'List HyperShift HostedClusters' with a specific scope condition 'when the hub is the HCP hosting cluster.' This clearly identifies the verb, resource, and distinguishing context from sibling tools like list_clusters.

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

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

The description explicitly explains when to use this tool: when the hub hosts the HCP control plane. It also names the alternative: 'the spokes still appear via list_clusters,' and clarifies the namespace behavior. This provides direct guidance on when to pick this tool versus 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 provide readOnlyHint, openWorldHint, and destructiveHint. The description adds valuable behavioral context beyond annotations by noting that it returns a 'rollout summary' and explaining the namespace filtering behavior (empty namespace means all namespaces). This complements the safety profile without contradicting it.

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

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

The description is concise and well-structured: a front-loaded main clause stating the purpose, a brief parenthetical clarifying the resource type, and a simple Args block. Every sentence earns its place, with no redundant or irrelevant 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?

For a simple list tool with one optional parameter, the description is complete: it explains the resource, the namespace behavior, and the rollout summary. Annotations cover safety and open-world aspects, and the presence of an output schema means return values need not be detailed. No critical gaps remain.

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

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

The input schema provides no description for the namespace parameter (0% coverage), but the tool description has a dedicated 'Args' section explaining that namespace limits to one namespace and empty lists across all namespaces. This fully compensates for the schema's lack of parameter documentation and adds clear semantic 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 uses the specific verb 'List' with the resource 'ManifestWorkReplicaSets' and adds a clarifying parenthetical explaining the resource as 'a template fanned across a Placement', which distinguishes it from sibling tools like list_manifestworks. It also mentions the 'rollout summary' output, making the tool's purpose unambiguous.

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

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

The description provides clear context through the resource definition but does not explicitly state when to use this tool versus alternatives such as list_manifestworks or list_placements. There is no mention of exclusions or a direct comparison to siblings, so the usage guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which covers safety. The description adds that the listing is scoped to a cluster and represents hub management, but does not disclose open-world behavior (openWorldHint=true) or return format/pagination. Minimal added context beyond 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 extremely concise: one sentence plus a compact Args block. No filler or redundancy; every word contributes to understanding the tool's purpose and parameter.

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 simplicity (one param), presence of an output schema, and clear annotations, the description is sufficient for selection and invocation. It could mention when to use this instead of get_manifestwork or list_manifestworkreplicasets, but this is not critical for a basic list tool.

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

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

The input schema has 0% description coverage, but the description's 'Args' section clarifies that 'cluster' is the managed cluster name, which is the essential semantic. This compensates for the bare schema, though it is sparse for a single 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 states the action 'List', the resource 'ManifestWorks', and a specific scope 'targeting a cluster' with added context 'what the hub is managing there'. This distinguishes it from sibling tools like get_manifestwork (singular) and list_manifestworkreplicasets.

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 clear usage context: use this to see what the hub is managing on a specific cluster. It does not explicitly enumerate alternatives or exclusions relative to siblings like get_manifestwork, but the listing verb and per-cluster scope provide sufficient guidance for 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 convey read-only and non-destructive behavior, and the description adds meaningful details about namespace and cluster filtering semantics. It does not mention pagination or output shape, but an output schema exists and the safety profile is already annotated.

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

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

The description is concise, front-loaded with a clear purpose line, and then uses a structured Args block. Every sentence is informative 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?

For a simple read-only list tool with two optional parameters and an output schema, the description covers the purpose, parameter semantics, and filtering behavior. The presence of the output schema means return values need not be explained.

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, but the description's Args section fully explains both parameters, including the empty namespace default and the optional cluster filter. This fully compensates for the schema gaps.

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 'List HyperShift NodePools (worker groups)' with optional filtering to one HostedCluster, making the action and resource explicit. It distinguishes this from sibling tools like list_hosted_clusters or list_clusters by its specific target.

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

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

The description provides clear context on when to use the tool, including that an empty namespace lists across all namespaces and that cluster is optional. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific scope and state of the listed CSRs, but does not disclose additional behavioral traits like pagination, ordering, or potential size. With the output schema present, this is adequate but not rich, so a 3.

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 sentence that starts with the verb 'List' and efficiently packs in the resource type, state, and approval context. There is no redundancy or unnecessary 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?

For a simple no-parameter listing tool with read-only annotations and an output schema, the description fully specifies what is listed and under what condition. It doesn't need to cover return shape or safety, as those are handled by structured data, making it contextually complete.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The input schema is empty and coverage is trivially 100%, so the description need not compensate; the zero-param baseline of 4 applies.

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

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

The description uses the specific verb 'List' and identifies a distinct resource type: 'cluster-join / add-on registration CSRs awaiting hub approval'. This clearly distinguishes it from sibling tools like list_cluster_claims or list_pending_proposals, which cover different resources or scopes.

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

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

The description clearly implies when to use this tool: to see pending CSRs for cluster-join or add-on registration awaiting hub approval. It doesn't explicitly name alternatives or exclusions, but the specific CSR scope gives clear usage context, warranting 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 already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context about the resource types and the approval filter, but does not disclose additional behaviors such as pagination, ordering, or how proposals are represented. 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 single, front-loaded sentence. It immediately states the action ('List proposals'), adds scoping in parentheses, and includes the approval filter—no wasted words.

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

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

This is a simple, zero-parameter list tool with annotations and an output schema. The description explains what the tool returns (proposals pending approval, specifically ManifestWorks and cluster actions), which is sufficient 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?

The tool has zero parameters, and the input schema confirms this. With no parameters to document, a baseline of 4 is appropriate; the description correctly focuses on the returned data rather than 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 clearly says 'List proposals' and specifies the two kinds (ManifestWorks and cluster actions) plus the filter 'waiting for human approval.' This distinguishes it from sibling tools like list_manifestworks (which lists all manifestworks) and list_pending_csrs (which lists pending certificate requests).

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 a clear use case: retrieve proposals that need human approval. It does not explicitly name alternatives or exclusions, but the 'waiting for human approval' qualifier provides solid contextual guidance for when to use this tool instead of other list tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds behavioral context by explaining that each placement's output includes how many clusters it currently selects, and how namespace filtering works. This goes beyond the annotations without contradicting them.

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 extremely concise—two lines—and front-loaded. The first sentence states the primary function, and the second clarifies the parameter. Every word is useful, with no fluff or repetition.

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

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

Given the tool's simplicity (one optional parameter), the presence of an output schema, and strong annotations, the description covers all necessary context. It explains the core listing behavior, the namespace filter, and the cluster-count output. No critical gaps remain.

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

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

The input schema has 0% description coverage, so the description must compensate. It fully explains the only parameter (namespace): "limit to one namespace; empty lists across all namespaces." This provides complete semantic guidance beyond the schema's bare type/default.

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 says "List Placements and how many clusters each currently selects," which is a specific verb (list), a clear resource (Placements), and an informative output scope (cluster counts). It distinguishes itself from siblings like get_placement_decision or list_clusters by focusing on placement-to-cluster counts.

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 context on using the namespace parameter (limit or list all), but it does not explicitly discuss when to prefer this tool over related siblings (e.g., get_placement_decision) or when not to use it. The usage is implied from the name and description but not formally guided.

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

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

The description adds behavioral context beyond the readOnlyHint and destructiveHint annotations by noting the add-on dependency and explaining the namespace parameter's effect on scope. It does not contradict 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 brief, directly to the point, and uses a clear Args section to document the parameter without unnecessary verbosity.

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 simple nature of the tool with one optional parameter and an existing output schema, the description covers the functional scope and prerequisite. It leaves some ambiguity about behavior when the add-on is not installed, but overall it's 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 description provides complete semantics for the only parameter, namespace, explaining that a value restricts to one namespace while an empty value covers all namespaces. This fully compensates for the 0% schema description coverage.

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

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

The description clearly states a specific action ('List') on a defined resource ('governance Policies and per-cluster compliance'), which distinguishes it from related list tools like list_policy_violations, though it doesn't explicitly name alternatives.

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

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

There is no explicit guidance on when to use this tool versus sibling tools such as list_policy_violations. The only condition mentioned is add-on installation, which is a prerequisite rather than a usage comparison.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds no contradicting behavior. It does add the filtering semantics (only noncompliant/pending, fleet-wide), but does not disclose other behavioral details like pagination or sorting, which are likely covered by the output schema.

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

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

The description is a single sentence fragment, which is highly concise and front-loads the core message. The trailing phrase 'the open risks' adds interpretive value but is slightly redundant with 'NonCompliant / Pending', so it is not perfectly tight.

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, filtered list tool with strong annotations and an output schema, the description provides sufficient context to understand what the tool returns and why it exists. It could explicitly mention complementing list_policies, but the current level of detail is adequate for 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?

The tool has zero parameters, and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The baseline of 4 is appropriate for tools with no 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 clearly states the tool returns only noncompliant or pending policy-cluster pairs across the fleet, which is specific and distinguishes it from sibling tools like list_policies. The verb 'list' is implied by the tool name, but the scope and resource are clearly defined.

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

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

The description implies usage for surfacing open risks by mentioning 'NonCompliant / Pending' and 'open risks', but it does not explicitly name alternatives or provide when-not-to-use guidance. It relies on the agent to infer that this tool is a filtered subset of list_policies.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by disclosing the 'identity + conditions only' limitation, meaning it returns only identity fields and conditions, not full resource bodies. It also clarifies the allow-list restriction and explicitly excludes secrets, which is 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 concise, front-loaded, and structurally organized with an Args section. Every sentence contributes meaningful information (purpose, parameter explanations, allow-list restriction). No fluff or repetition.

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

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

Given the tool's simple nature, an output schema exists and the description does not need to detail return values. It covers scope (allowed types), namespace semantics, and security constraints. The phrase 'identity + conditions only' is left somewhat vague, but overall it provides sufficient context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains 'resource' with concrete examples (managedclusters, placements, etc.) and defines 'namespace' behavior ('limit to one namespace; empty lists all'). This adds meaning beyond bare schema property names, though it does not exhaustively list valid resource 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 the tool performs a 'Generic list' over 'an allow-list of OCM API types', with specific verb ('list') and resource scope. It distinguishes itself from specialized siblings (e.g., list_placements) by being generic, and enumerates example resource types, 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 provides clear context on when to use the tool: for OCM API types on the allow-list. It explicitly states an exclusion—'Secrets and other credential resources are not on the allow-list and cannot be read'—which is a when-not condition. However, it does not name alternative tools for disallowed resources, so it lacks explicit 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?

Discloses server-side dry-run validation, pending storage, and the mandatory human approval step via `ocm-mcp approve`. It also details per-action side effects such as cordon tainting, CSRs approval, and addon deletion, which go well beyond the provided 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 starts with a concise purpose statement, uses a compact bulleted Args list, and every sentence contributes essential information. No filler or repetition is present.

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

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

Covers action selection, parameter requirements, validation behavior, pending storage, and the approval handoff. With an output schema present, omitting return-value details is acceptable, making the description complete for this 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?

Despite 0% schema description coverage, the Args section fully documents all four parameters, enumerates valid action values, and specifies which actions require params_json fields. This completely compensates for the schema's lack of 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 first sentence clearly states a specific verb ('Propose') and resource ('OCM cluster lifecycle action'), and immediately clarifies that it does NOT apply anything, distinguishing it from the sibling apply_cluster_action and other cluster-action 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 provides detailed per-action semantics and explains the propose/approve flow, including the need for a human operator to run `ocm-mcp approve`. It does not explicitly name alternative tools, but the 'Does NOT apply anything' and 'stored pending' behavior make the usage context 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behaviors: the proposal is not applied, must pass static guardrails and a Kyverno dry-run, is stored pending, and requires an explicit approval token. These details go well beyond the structured fields.

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

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

The description is well-structured: a one-sentence purpose statement, a bulleted Args block with inline explanations, and a concise workflow paragraph. 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?

Given the output schema exists and the description covers inputs, constraints (allowed kinds, pinned images), validation (guardrails, dry-run), and follow-up approval, the context is complete for an AI agent to invoke the tool correctly and set expectations.

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%, the description provides essential semantics for all four parameters: cluster (target name), name (kebab-case), summary (human-readable justification), and manifests_json (JSON array with allowed kinds, namespaced, pinned images). This fully compensates for the minimal 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 uses a specific verb 'Propose' with resource 'a change to one cluster as an OCM ManifestWork' and explicitly states 'Does NOT apply anything', clearly distinguishing it from sibling tools like apply_manifestwork. It also mentions the pending approval workflow, further clarifying its role.

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

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

The statement 'Does NOT apply anything' provides a clear when-not condition, and the description explains the approval workflow (human operator must approve). However, it does not explicitly name alternative tools or state 'Use this when X, use apply_manifestwork when Y', so it stops short of full 5.

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

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

Adds meaningful context beyond annotations: 'Applies nothing' clarifies it is non-destructive, 'Creates a distinct rollback proposal bound to the exact ManifestWork name and UID' details the side effect, and the token restriction is disclosed. This complements the annotations (readOnlyHint=false, destructiveHint=false) rather than contradicting them.

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

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

The description is compact and starts with the core purpose. The 'Args:' section is slightly redundant with the explanation already in the prose, but it remains clear and focused, earning a high conciseness score.

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

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

Given the tool's low complexity (single parameter), the description sufficiently covers prerequisites (already-applied ManifestWork), the approval flow, and security considerations. An output schema exists, so return details are not needed. Minor gaps: no mention of error cases or what happens after approval, but not critical for a proposal 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?

While schema description coverage is 0%, the description explicitly defines the parameter: 'proposal_id: id of an already-applied ManifestWork proposal.' This adds semantic meaning beyond the schema's bare type declaration, fully compensating for the missing schema 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 action: 'Propose rolling back an applied ManifestWork' with the clarification 'Applies nothing; needs its own approval.' This distinguishes it from direct rollback or apply tools (e.g., rollback_manifestwork, apply_manifestwork) by emphasizing it is a proposal, not the actual mutation.

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 contextual guidance: 'needs its own approval' and explains that 'an old apply token can never delete a workload'—implying this is the safe way to initiate a rollback that requires human authorization. It does not explicitly name alternatives, but the sibling context (rollback_manifestwork) makes the comparison implicit.

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?

While the annotations already declare read-only and non-destructive behavior, the description adds valuable behavioral context: events are returned newest first, namespace filtering defaults to all namespaces when empty, and the limit defaults to 40. These details go beyond the annotation coverage.

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

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

The description is concise and well-structured: the opening line states the purpose, the Args block covers parameters, and a final sentence gives the use case. No words are wasted, and important 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?

Given the tool's simple read-only nature, the presence of an output schema, and the rich annotations, the description covers all essential aspects: what it does, when to use it, parameter semantics, and behavioral details. It is complete for its 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?

With zero description coverage in the input schema, the description fully compensates by explaining each parameter: cluster (managed cluster name), namespace (optional filter, empty means all), and limit (maximum events, default 40). This is all an agent needs to invoke the tool correctly.

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 that the tool returns recent Kubernetes events from a managed cluster, newest first. This specific verb-resource combination distinguishes it from sibling tools like get_pod_logs and get_audit_trail. The use case for troubleshooting unhealthy pods further clarifies its role.

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

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

The description explicitly says to use this tool to find the root cause of unhealthy pods, providing a clear context. It does not name alternative diagnostic tools or exclusion criteria, but the guidance is specific enough for an agent to select it appropriately.

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 destructiveHint=true and readOnlyHint=false. The description adds valuable context about the approval workflow and the need for an approval_token, which is not fully captured by the annotations. It does not contradict annotations, and it supplements them with prerequisite details.

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

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

The description is concise and front-loaded with the main purpose, followed by a brief Args list. Every sentence earns its place, and there is no redundant information. It is efficiently structured for quick comprehension.

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

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

The description covers the essential aspects: purpose, prerequisites, and parameter sources. Given the tool's simplicity and the presence of an output schema, it is largely complete. However, it could explicitly mention that the operation is irreversible or that the token is single-use, though this is partially implied by 'Delete' and the destructiveHint annotation.

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 fully explain the parameters. It does: rollback_proposal_id is 'id returned by propose_rollback' and approval_token is 'a rollback token from ocm-mcp approve <rollback-id>'. This adds meaningful guidance beyond the schema's bare names/types.

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

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

The description clearly states the action: 'Delete a ManifestWork after a rollback proposal has been approved.' It uses a specific verb (Delete), identifies the resource (ManifestWork), and includes a condition (after approval), which distinguishes it from sibling tools like propose_rollback and apply_manifestwork.

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 when-to-use context by specifying 'after a rollback proposal has been approved' and explains how to obtain the required arguments (rollback_proposal_id from propose_rollback, approval_token from ocm-mcp approve). It does not explicitly mention alternatives or exclusions, but the workflow is clear.

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