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

Although annotations already indicate readOnlyHint=false and destructiveHint=false, the description adds critical behavioral context: the API mapping to POST /alerts?action=takeownership, the control state ASSIGNED, and the preview behavior with confirmed=False. This goes well beyond the annotations and clearly discloses how the tool behaves.

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

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

The description is well-structured and front-loaded with the main purpose. It then explains the mapping, provides usage guidance, and lists parameters. Every sentence adds value, and the length is appropriate for the complexity of the tool.

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

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

Given the tool's moderate complexity and lack of output schema, the description covers all essential aspects: what the tool does, how it maps to the underlying API, when to use it, how to confirm changes, and parameter details. The preview behavior is disclosed, which implies the response format enough for the agent.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: alert_id (the UUID to acknowledge), confirmed (must be True to actually acknowledge, default False = preview), and target (Aria target name from config). This adds meaning beyond the raw 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 specific action ('Acknowledge an active alert by taking ownership') and explicitly contrasts it with cancel_alert, clearly distinguishing the tool's purpose from a sibling. The verb 'acknowledge' plus resource 'alert' is specific and unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use this when you want to own the alert without closing it; cancel_alert closes it for good.' It also explains the default preview mode, giving clear context on when the tool actually mutates or not.

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 destructive is true and readOnly is false, but the description adds meaningful nuance: the operation is permanent, won't re-trigger unless condition recurs, and confirmed=False returns a preview without making changes. This goes well beyond the annotation metadata.

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, well-structured, and front-loaded with the core action. The 'Args' section is minimal and each line adds value without repetition. It avoids padding and stays under a reasonable length for the tool's complexity.

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

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

For a destructive cancellation tool with no output schema, the description covers what the agent needs: what it does, when to use it, what happens on confirm/cancel, and all parameters. The sibling context (acknowledge_alert) is also considered, making the description complete for operational use.

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 carries the full burden. It clearly explains alert_id as the alert UUID, confirmed as a safety switch requiring True to actually cancel with default False preview mode, and target as an Aria target name from config with a sensible default. This fully 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 description starts with 'Cancel (dismiss) an active alert' and explicitly states it is a WRITE operation that permanently closes the alert. It clearly identifies the resource (alert) and the specific action (cancel/dismiss), and does not get confused with acknowledge_alert.

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

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

The description gives explicit usage guidance by pointing to acknowledge_alert when the user only wants to mark an alert as seen. It also explains the behavioral distinction: cancelled alerts will not re-trigger unless the underlying condition recurs, helping the agent choose correctly between similar 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 discloses several behavioral traits beyond the annotations: it returns the new definition's id and name, notes name uniqueness ('must be unique in Aria Operations'), explains OR logic for symptom_definitions, and specifies default adapter_kind and target. This adds valuable context without contradicting the annotations (readOnlyHint=false is consistent with '[WRITE]').

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 longer than average but well-structured: a clear opening sentence, return value note, usage guidelines, and a parameter list. The parameter list duplicates the schema but is necessary given 0% schema coverage. Every sentence serves a purpose, though it could be slightly tightened.

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

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

Given that there is no output schema, the description adequately covers the return value (id and name). It also covers prerequisites, parameter details, defaults, and alternatives, making it complete for a complex creation tool with 7 parameters.

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's concise parameter explanations are essential. It details each parameter's meaning, valid values (e.g., resource_kind options, criticality levels), defaults, and the role of symptom_definition_ids. This fully 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 description clearly states 'Create a new alert definition referencing existing symptom definitions' with a specific verb and resource. It also distinguishes itself from siblings by mentioning the return of id and name and contrasting with set_alert_definition_state.

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

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

Provides explicit usage guidance: 'Run list_symptom_definitions first for symptom_definition_ids' and 'to silence an existing definition use set_alert_definition_state rather than creating a variant.' This names the exact alternative and prerequisite, making it clear when to use this tool versus others.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical details: the operation is irreversible, active alerts from the definition are not affected, and the confirmed=False preview mechanism. This significantly enriches the behavioral model beyond what annotations alone convey.

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

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

The description is well-structured and front-loaded with the core purpose, followed by essential caveats and a clean Args section. Every sentence provides valuable information without redundant padding.

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 tool's complexity fully: all parameters are explained, the destructive nature is clear, the preview/default flow is disclosed, and the alternative tool is suggested. There is no output schema, but the preview behavior is described, making the tool's behavior adequately specified.

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 carries the full burden and does so excellently. It explains definition_id as the UUID to delete, confirmed as requiring True to actually delete with a default of False for preview, and target as the Aria target name from config with a 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 opens with 'Permanently delete an alert definition,' using a specific verb and resource that clearly states the operation. It also notes 'Irreversible,' which distinguishes it from sibling tools like set_alert_definition_state that only silence a definition.

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 provides an alternative: 'Use set_alert_definition_state(enabled=False) instead to silence a definition you may want back.' The irreversibility warning and the preview default also communicate when not to proceed, making the usage context very clear.

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

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

Annotations already mark destructiveHint=true, but the description goes well beyond by explaining the deletion is permanent, irreversible, audit-logged, and limited to the report instance (not definition/schedules). It also discloses the confirmation/preview behavior and the error condition for nonexistent IDs, adding substantial behavioral context not present in annotations or 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 well-structured with a concise explanatory paragraph followed by an Args section. Every sentence contributes meaningful information, and the inclusive 'Args' block is consistent with the schema. The length is appropriate for the complexity of a destructive operation with a safety confirmation flag.

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

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

Given the tool has no output schema and only three simple parameters, the description covers the essential context: what is deleted, what is preserved, irreversibility, audit logging, error behavior, prerequisites, and the preview mechanism. It is complete enough for an agent to safely and correctly invoke the tool.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters. It clearly explains report_id as a UUID from generate_report or list_reports, confirmed must be True to actually delete (default False preview), and target as an Aria target name from config with a default. This fully compensates for the schema's minimal titles.

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

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

The description uses a specific verb 'Permanently delete' plus the resource 'generated report artifact' and clearly distinguishes from siblings by noting that only the report instance is removed while definitions and schedules remain. It also connects to generate_report for recreation, which differentiates it from related tools like get_report or list_reports.

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 for deleting generated report instances, tells the user to call list_reports first to find valid UUIDs, and notes that re-running generate_report recreates the artifact. It does not explicitly say 'when not to use' or name an alternative tool for deleting report definitions, but the context is sufficient and the sibling list reinforces the intended use.

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, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: returns finding summaries with specific fields in a 'paginated envelope,' filter behavior (comma-separated, omit to match all), a default limit of 50, and the distinction from compliance findings. There is no contradiction with annotations.

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

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

The description is well-structured and front-loaded. It begins with a bolded [READ] tag and a clear purpose, then adds usage context, return details, and an exclusion note. The Args list is clean and scannable. Every sentence adds value, and the length is appropriate given five parameters and the need for behavioral nuance.

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

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

For a read-only list/filter tool with no output schema, the description fully covers purpose, usage, parameters, return format (paginated envelope with specific fields), and an explicit mention of an alternative tool for compliance. It is self-contained and gives the agent everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry the full burden. It does so effectively by documenting every parameter in the Args section: severities with an example ('CRITICAL,WARNING'), categories, finding_types, limit with default, and target ('from config; default when omitted'). This fully 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 description clearly states the tool's function: 'List Operations diagnostic findings, optionally filtered.' It specifies the resource (diagnostic findings), the verb (List), and the scope ('across the environment'). It also distinguishes this tool from compliance-related tools by explicitly noting 'NOT compliance benchmark results.'

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

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

It provides explicit guidance on when to use the tool: 'Use this to review current diagnostic findings (misconfigurations, health rule hits) across the environment.' It also gives an explicit alternative and exclusion: 'for hardening/compliance use vmware-harden.' This is clear and actionable.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's read-only statement is partially redundant. However, it adds the paginated envelope field names and the defensive-read gotcha, which are valuable behavioral insights beyond the structured hints.

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 bold [READ] prefix, a concise purpose sentence, a return-format note, a gotcha, and an Args section. Every sentence carries useful information, and no filler 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?

Despite having no output schema, the description covers purpose, when to use, the return envelope, parameter behavior, and a behavioral gotcha. This is sufficient for an agent to select and safely invoke the tool for a read-only listing operation.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining `limit` (max certificates, default 50, None returns all) and `target` (Aria/VCF target name from config, default omitted). This gives actionable meaning beyond the bare schema definitions.

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

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

The description begins with "[READ] List certificate status and expiry across the VCF fleet," which clearly identifies the verb, resource, and scope. This distinguishes it from all sibling tools, none of which deal with certificates.

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 states when to use it: "Use this to spot certificates that are expired or expiring soon across all VCF components managed by Operations 9.1." It does not explicitly name alternatives or exclusions, but the use case is clear and well contextualized.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context: returns a paginated envelope, domain summaries, a 404 meaning the integration_id is wrong, and a note that the tool does not list VCF integrations—these are valuable 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 structured with a clear title line, usage context, error handling, and an Args block. Each sentence provides necessary information without redundancy, and the layout makes it easy to scan. It is appropriately sized for the tool's complexity.

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

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

With no output schema, the description still informs the agent of return contents (domain summaries with id, name, type, status) and the paginated envelope. It covers purpose, usage, parameter details, and error semantics, making it self-sufficient for a 3-parameter read-only 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?

Although the schema lacks descriptions (0% coverage), the description comprehensively explains all three parameters: integration_id is a UUID from the Operations UI, limit defaults to 50 and None returns all, and target defaults to config. This fully compensates for the absent schema descriptions and adds precise 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 opens with '[READ] List the SDDC/workload domains behind one registered VCF integration', using a specific verb and resource that clearly distinguishes this tool from siblings like fleet_certificate_list or list_resources. It also specifies the domain summaries returned (id, name, type, status), leaving no ambiguity about its function.

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

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

It explicitly says 'Use this to enumerate the domains of a VCF integration registered in Operations' and explains where to find the integration_id, providing clear context for when to invoke it. It does not name alternative tools or give explicit 'when not to use' exclusions, but the instruction that this skill does not list VCF integrations implies a prerequisite and limits usage 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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable context by stating that the rotation endpoint is 'deliberately not wired' and by flagging a gotcha that unknown response fields degrade to empty. This goes beyond simply echoing the annotations, providing genuine behavioral insight.

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 tightly structured with a [READ] tag, a purpose statement, a usage note, a gotcha, and an Args section. Every sentence earns its place; there is no redundancy or fluff. The format is easy to scan and parse.

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

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

Given the tool's simplicity (two optional params, no output schema, read-only), the description covers all essential context: what it does, return format summary, read-only guarantee, a gotcha, and parameter meanings. It is complete enough for an agent to select and invoke correctly without additional information.

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 explaining parameters. It does so thoroughly: 'limit' is explained with default and None behavior, and 'target' is described with its config source and default behavior. This fully compensates for the missing schema descriptions.

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

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

The description opens with a clear verb+resource: 'List managed password-account status across the VCF fleet.' It explicitly states the scope (fleet-wide) and distinguishes itself from sibling tools like fleet_certificate_list and fleet_domain_list by focusing on password accounts. The 'Use this to review...' sentence reinforces the purpose.

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

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

The description provides clear context for when to use the tool ('Use this to review which fleet accounts Operations manages and their rotation/expiry status') and hints at what it doesn't do (rotation). However, it does not explicitly mention alternative tools or when-not-to-use conditions, 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?

The description discloses crucial behavioral traits: returns immediately with report_id and PENDING status, does not wait for the file, uses the first resource ID as the single root resource, and suggests passing a cluster/datacenter UUID to cover children. These details go beyond the annotations (readOnlyHint=false, idempotentHint=false) and add significant value.

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

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

The description is well-structured and every sentence earns its place. It includes the workflow, parameter details, and notes on resource behavior without redundancy, making it appropriately sized for the tool's complexity.

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 an async report-generation tool with no output schema, the description covers all essential aspects: the trigger action, immediate return, polling workflow, root-resource behavior, and how to source parameters. Sibling tools are referenced where relevant, making the description 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 description explains each parameter meaningfully: definition_id from list_report_definitions, resource_ids requiring at least one and using the first as root, and target defaulting when omitted. Schema coverage is 0%, so this is essential. However, it incorrectly labels resource_ids as REQUIRED while the schema marks it optional (default null), which may mislead agents.

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 triggers generation of a report from a report definition template, using the specific verb 'Trigger'. It distinguishes itself from siblings like get_report (polling status) and list_reports (listing reports). The [WRITE] tag also reinforces the mutating nature.

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 poll get_report(report_id) until COMPLETED and then use download_url, and directs users to list_report_definitions and list_resources for finding IDs. This provides clear sequential usage, though it does not explicitly contrast with alternatives like list_reports or delete_report.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, which covers safety. The description adds useful behavioral context beyond annotations: the Alert model does not carry a resource name, and recommendations hang off the alert definition, not the alert. This helps set expectations about what the tool can and cannot return.

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 somewhat lengthy but well-structured, front-loading the purpose and usage, then return details, caveats, and arguments. Every sentence carries informative weight, though a more concise version could have been slightly tighter without losing value.

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

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

With no output schema, the description thoroughly enumerates the returned fields and caveats (missing resource name, recommendations on alert definition), and points to related tools for follow-up actions. This makes the tool almost self-contained for an AI agent.

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

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

Schema has 0% description coverage, but the description fully compensates by explaining both parameters: alert_id is 'the alert UUID (from list_alerts)' and target is 'Aria target name from config; default when omitted.' It also clarifies the return object fields, giving meaning beyond the bare schema 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 explicitly states the tool's function: get full details for one alert by UUID, including contributing symptoms. It distinguishes itself from siblings like list_alerts (discover/filter) and investigate_alert (correlation), making it clear when this tool is the right choice.

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

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

Provides explicit guidance: use after list_alerts to drill into a single alert, use list_alerts to discover/filter, and use acknowledge_alert or cancel_alert to act on the alert. Also mentions investigate_alert as an alternative for correlation, fully covering usage context and alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds critical behavior beyond that: it explains that the tool reports OFFLINE on a 503 response from the platform and 'never raised,' meaning it remains usable even when Aria is down. It also discloses return fields (overall_status, healthy, system_time_ms, details), which the annotations do not cover.

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 summary line, a usage/behavior paragraph, and an Args section. It is somewhat verbose (e.g., repeating '[READ]' despite readOnlyHint annotations) but every sentence carries relevant information, and key points are front-loaded. A slight trim could make it tighter, but it is not wasteful.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, return values, edge-case behavior, and usage context. The only gap is that 'details' in the return value is not elaborated, but given the tool's simplicity and the use cases provided, this is a minor omission.

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 carries the full burden. The 'Args:' section states 'target: Aria target name from config; default when omitted,' which adds meaning beyond the schema's bare property. This clearly explains the parameter's purpose and optionality, though it could be more specific about where config names come from or how to list valid targets.

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

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

The description states a specific verb and resource: 'Check Aria Operations platform node status (ONLINE/OFFLINE).' It clearly distinguishes this from sibling tools like get_resource_health by focusing on platform-level health and explicitly noting that per-service breakdown is not exposed. The scope is unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use this to verify Aria Operations is functioning before investigating monitoring blind spots.' It also gives an alternative: 'When status is ONLINE but data looks stale, check list_collector_groups next.' The limitation 'per-service breakdown is not exposed by the public API' effectively states when not to use it, offering alternatives and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: capacity_remaining_pct exists only at group level and values are None while capacity analytics warm up. This helps the agent set expectations about the data returned.

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, opening with a [READ] marker and a single concise sentence that captures the core output. It then gives a brief caveat and usage guidance, followed by an Args block. Every sentence earns its place with no filler.

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

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

Despite no output schema, the description names the returned fields and their semantics, notes the warming-up edge case, and points to sibling tools for specific follow-ups. For a simple read tool with two parameters, this is complete enough 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?

Input schema has 0% description coverage, but the description's Args section compensates fully. It explains cluster_id is the cluster resource UUID from list_resources and target is an Aria target name from config with default when omitted. This adds meaning the schema lacks.

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 a capacity overview for a cluster, including group-level remaining-capacity percentage, per-dimension absolute remaining capacity, and projected days-until-full. It names specific metrics and explicitly differentiates from sibling tools get_remaining_capacity and get_time_remaining, leaving no ambiguity about scope.

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 says 'Start here when assessing overall cluster capacity health' and then gives explicit alternatives: 'for absolute headroom values use get_remaining_capacity, and for just the exhaustion projections use get_time_remaining.' This is excellent when-to-use guidance and distinguishes from siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds rich behavioral context: it explains the return structure (group-level capacity_remaining_pct, per-dimension remaining_value with units), the data source (OnlineCapacityAnalytics demand model), and the warm-up behavior (Values are None while capacity analytics warm up). No contradictions with annotations.

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

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

The description is well-structured with a leading [READ] tag, a clear purpose statement, a return summary, an edge-case note, and alternative tool pointers, followed by a concise Args section. Every sentence contributes value, and the information is front-loaded for quick scanning.

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

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

With no output schema, the description adequately explains what the tool returns (group-level percentage and per-dimension remaining values with units) and covers important context (None during warm-up, possible resource types). It also provides enough guidance for a moderate-complexity tool with two parameters, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining both parameters in an Args section: resource_id is a UUID for ClusterComputeResource or HostSystem from list_resources, and target is an Aria target name from config with a default when omitted. This adds significant meaning beyond the raw 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+resource ('Get remaining capacity headroom for a cluster or host') and explicitly distinguishes itself from sibling tools by naming get_capacity_overview and get_time_remaining for alternative views. This clearly defines what the tool does and how it differs.

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

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

The description provides explicit when-to-use guidance by stating 'Use get_capacity_overview for the combined view, or get_time_remaining for projected days-until-full.' It also notes that values are None while analytics warm up, implying users should wait or avoid relying on it during that period. This fully orients the agent on appropriate usage.

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

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

Despite annotations already declaring readOnly and idempotent hints, the description adds non-obvious behavioral context: download URLs are always constructed, so a URL may exist even when the report is PENDING and must not be fetched until status is checked. This is exactly the kind of caveat that prevents misuse.

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 bracketed read indicator, a one-sentence summary, a compact list of return fields, an important caveat, and an Args block. Every sentence earns its place, and the critical caveat is prominently placed before the parameters.

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 two parameters, no output schema, and strong annotations, the description still covers the return fields, the polling workflow, the URL caveat, and parameter origins. An agent has everything needed to select and correctly invoke 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?

Schema description coverage is 0%, but the description fully compensates by explaining report_id as the UUID from generate_report or list_reports, and target as an Aria target name from config with a default. This adds meaning far beyond the raw schema property 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 opens with '[READ] Get status and download URLs for a generated report,' which clearly identifies a specific verb and resource. It also differentiates the tool from siblings like generate_report and list_reports by emphasizing its role as a status/URL retriever for an already-generated report.

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

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

The description explicitly instructs 'Use this to poll after generate_report,' giving clear context for when to invoke this tool. However, it does not contrast with list_reports or state when not to use it, so it stops short of full exclusion 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 read-only, idempotent, non-destructive behavior. The description adds valuable context about return fields, badge score behavior (null when not scored), and the target parameter's default behavior, going 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 well-structured with a [READ] prefix, a clear purpose statement, and concise details. Every sentence adds value, including usage guidance and parameter explanations.

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 and strong annotations, the description provides complete context: what is returned, how to use it, and alternatives. The lack of an output schema is mitigated by listing the return fields.

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?

Even though schema description coverage is 0%, the description explicitly explains resource_id as the UUID from list_resources and target as the config target name with default behavior. This fully compensates for the schema's bare type definitions.

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

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

The description clearly states the tool returns a single resource object and enumerates the fields. It distinguishes itself from siblings by noting it is used after list_resources and does not accept a name, 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?

Explicitly states when to use the tool ('after list_resources to inspect a single UUID') and provides alternatives for other use cases (get_resource_health for badges, get_resource_metrics for metrics). Includes a clear constraint (does not accept a name).

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 idempotentHint annotations, the description discloses return structure (badges[]), score range and meaning, and the null/-1 behavior when Aria hasn't computed a badge. This adds non-obvious behavioral context.

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

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

Description is tightly structured with a purpose statement, return explanation, usage alternatives, edge-case note, and an Args block. Every sentence adds value; 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 two-parameter read tool with no output schema, the description covers return values, score interpretation, null semantics, and alternatives. It is self-sufficient 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 has 0% description coverage, but the description fully explains both parameters: resource_id as 'The resource UUID' and target as 'Aria target name from config; default when omitted.' This compensates entirely 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?

Description opens with a clear verb and resource scope: 'Get the health, risk, and efficiency badge scores for a resource.' It explicitly differentiates from sibling tools by directing users to get_resource for the whole object and list_alerts for alert details.

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

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

Provides explicit when-to-use guidance: 'Use this when the scores are all you need' and names alternative tools with their purposes. Also explains the null/-1 caveat for uncomputed badges, preventing misinterpretation.

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 idempotent. The description adds meaningful behavioral context beyond annotations: returns a dict keyed by metric key with {timestamp_ms, value} points, explicitly 'not an envelope,' and that keys with no data are omitted from the result. This goes beyond the annotation safety profile.

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

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

The description is well-structured and front-loaded with the purpose. Each sentence earns its place: the [READ] tag, the return format, the sibling comparison, the missing-key caution, and the Args block with defaults and examples. No filler or redundancy.

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

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

With 5 parameters, no output schema, and zero schema descriptions, this description provides complete context: return shape, key omission behavior, parameter defaults, and example metric keys. The only possible omission is error behavior/rate limits, but for a read-only metrics tool this is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries sole responsibility for parameter semantics. It explains every parameter: resource_id as UUID, metric_keys with concrete examples, hours with default, rollup_type with the allowed aggregation values and default, and target default from config. This fully compensates for the absent schema descriptions.

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

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

The description clearly states 'Fetch time-series metric statistics for a resource' with a specific verb and resource scope. It further distinguishes itself from the sibling tool get_resource_health by explicitly noting this is for history while the sibling is for a single current score.

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

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

The description provides explicit use guidance: 'Use this for history; for a single current score use get_resource_health instead.' It also warns about absent keys, telling the agent to check which keys came back before reporting a metric as zero, which is essential for correct interpretation.

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 idempotentHint annotations, the description explains return fields (risk_score, risk_color), the null condition when Aria hasn't computed a badge, and what the badge does not include. This provides substantial behavioral context not evident from annotations alone.

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

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

The description is well-structured and front-loaded with the [READ] tag and main purpose. Every sentence adds value—purpose, context, usage guidance, and parameter explanations—without redundancy or filler.

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

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

For a simple read tool with no output schema, the description covers the key contextual details: what it returns, the meaning of the score, the null edge case, and how to get more detail via list_alerts. It is complete for the agent to decide when and how to invoke it.

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

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

Although schema description coverage is 0%, the description compensates with an Args section that explains both parameters: resource_id is 'The resource UUID' and target is 'Aria target name from config; default when omitted.' This adds meaning beyond the raw schema.

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

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

The description clearly states 'Get the risk badge score for a resource (0–100, higher = more risk of future problems)', using a specific verb and resource. It distinguishes from sibling tool get_resource_health by noting it returns 'health and efficiency alongside it'.

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

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

Explicitly states when to use: 'Use this when the risk number is all you want' and names the alternative get_resource_health. It also instructs to use list_alerts for contributing alerts when the badge doesn't say what's wrong.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds crucial semantics: None values during analytics warm-up do not mean unlimited, preventing a common misread. This is meaningful behavioral disclosure beyond the structured metadata.

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-ordered: purpose, output, alternative, caveat, and args. The [READ] prefix signals intent. Every sentence contributes, with no fluff.

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

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

With no output schema, the description adequately describes the return structure (per-dimension entries with projected days) and the warm-up caveat. It leaves some depth unexplained (e.g., calculation method), but that's not essential for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 0%, but the description explains both parameters: resource_id is the resource UUID with an example type, and target is the Aria target name from config with default when omitted. This compensates for the barren schema, though it could be more specific about target's source.

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

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

The description opens with a clear action: 'Predict when a cluster will exhaust its capacity based on usage trends.' It also specifies the return payload (time_remaining per dimension) and explicitly contrasts with sibling get_capacity_overview, making the tool's unique scope unmistakable.

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 instructs: 'Use get_capacity_overview instead when you also want current headroom' and notes this tool returns only projections. This gives an explicit decision rule and names the alternative.

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

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

Despite strong annotations (readOnly, idempotent, etc.), the description adds valuable behavioral context by defining the paginated envelope, including the 'truncated' flag and the note that 'total' may be null. This goes beyond annotation hints and helps the agent handle responses correctly.

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 tightly organized into a summary line, output details, and parameter list. Every sentence adds value, with no unnecessary filler. The structure makes it easy to scan and parse.

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

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

Given the 4 parameters and no output schema, the description provides all essential information: purpose, usage guidance, response envelope structure, and parameter semantics. It is fully adequate 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?

The schema provides no descriptions (0% coverage), but the description compensates fully with detailed Arg explanations: metric_key gets example values, resource_kind gets a default, top_n gets a max and default, and target is explained as a config reference. This is exemplary parameter documentation.

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

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

The description states a specific action ('Query resources with highest consumption of a given metric') and clearly identifies the resource type and metric. It also distinguishes itself by mentioning the follow-up call to get_resource_metrics for history, making its role clear among siblings.

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 indicates when to use the tool (to get top consumers) and directs the agent to call get_resource_metrics on a returned id for history, providing a clear alternative/additional step. It does not leave ambiguity about its primary use case.

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, openWorldHint, idempotentHint), the description discloses the server-side correlation process, the five always-present return keys, and the degradation behavior when a resource is unresolvable. This adds valuable context about what actually happens during execution.

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?

While the description is detailed, every sentence serves a purpose: the [READ] tag sets expectations, the why-to-use rationale, the return structure, and the gotchas. It is front-loaded with the most important information and well-structured, earning its length.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description explains return keys, error handling, and usage constraints thoroughly. It provides all necessary information for an agent to invoke the tool correctly and interpret the result.

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 fully compensates. It explains alert_id as 'the alert UUID from list_alerts (not the resource UUID)' and target as 'Aria target name from config; default when omitted.' This is exactly the semantic meaning the schema lacks.

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

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

The description opens with a specific verb+resource: 'Resolve one alert to its affected resource in a single call' and explicitly distinguishes itself from the alternative of chaining get_alert and get_resource. This clearly identifies the tool's purpose and differentiates it from sibling tools.

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

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

Usage is explicitly scoped: 'use this instead of chaining get_alert then get_resource by hand.' It also provides a clear when-not-to-match instruction ('Never match the resource against vCenter inventory unless correlation.confirmed is true') and warns against a common mistake (mixing alert_id with resource UUID). This gives actionable guidance for correct use.

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, idempotent, and non-destructive behavior; the description adds value by disclosing the paginated envelope structure (items, returned, limit, total, truncated, hint) and the caveat about 'total' being null when the API reports no size. It also reveals the derived nature of 'criticality' and the absence of top-level 'enabled' field, which are useful behavioral quirks 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 front-loaded with a clear purpose statement, then provides necessary behavioral and parameter details in a structured format. While a bit dense, every sentence adds information—pagination behavior, integration with set_alert_definition_state, and parameter constraints—so it is appropriately sized for the tool's complexity.

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?

Without an output schema, the description compensates by explicitly describing the return envelope and advising to check 'truncated' before treating the result as complete. It also connects to sibling tools (set_alert_definition_state) and clarifies model-level quirks. This is a self-contained and complete description for list_alert_definitions.

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 carry the parameter meaning. The 'Args' section fully explains all three parameters: name_filter (substring, case-insensitive), limit (1-500, default 100), and target (Aria target from config, default when omitted). This goes well beyond the bare schema definitions and gives the agent the needed context 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 opens with '[READ] List alert definitions (templates that generate alerts when triggered).' This clearly identifies the verb ('List'), the resource ('alert definitions'), and adds the clarifying parenthetical that these are templates, distinguishing them from alert instances (e.g., list_alerts). It also references set_alert_definition_state, showing awareness of related 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 clear usage context, explaining that alert definitions have no top-level criticality or enabled field and that returned IDs are meant to be passed to set_alert_definition_state for enabling/disabling. It also warns to check the 'truncated' flag before assuming completeness. However, it does not explicitly state when not to use this tool or name alternatives like list_alerts or list_symptom_definitions, 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses pagination behavior (truncated flag, total null when API reports no size), the need to check truncated, and the absence of resource names in the alert model. These are valuable behavioral details not present in structured 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: purpose first, then output summary, pagination details, and an Args section. Every sentence provides necessary information without redundancy, making it an appropriately sized and front-loaded description.

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

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

Given the tool has 5 parameters, no output schema, and no enum constraints, the description covers all essential aspects: the full parameter list with semantics, return envelope fields, pagination handling, and resource resolution guidance. It is comprehensive for a 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 0% description coverage, so the description carries the full burden. It thoroughly explains each of the 5 parameters, including defaults, allowed criticality values, the resource_id scope, and the limit range, adding meaning well beyond the schema's type declarations.

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 alerts from Aria Operations' with a specific verb and resource. It also enumerates the returned fields, distinguishing it from sibling tools like get_alert, acknowledge_alert, and list_alert_definitions.

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

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

The description provides clear context for when to use the tool, including a cross-reference to get_resource for resolving resource names. However, it does not explicitly state exclusions or contrast with alternatives such as get_alert for retrieving a single alert, 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?

While annotations already indicate read-only, idempotent, and non-destructive, the description adds substantial behavioral detail: the two execution modes, performance characteristics ('One stats call per VM'), pagination envelope fields (items, returned, limit, total, truncated, hint, scanned), and the critical caveat that truncated=true means VMs went unscanned. This goes far 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 well-structured, starting with a concise summary, followed by context, behavioral details, return envelope explanation, and an Arg list. Every sentence adds value — the length is justified by the tool's complexity, and the formatting makes it easy to parse.

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

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

There is no output schema, but the description fully explains the return envelope and its fields. It also covers the two call modes, edge cases (truncated flag), and performance implications. Given the complexity and the absence of an output schema, the description is complete enough for an agent to use effectively.

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

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

Schema coverage is 0% and the schema only provides types/defaults. The description compensates fully by explaining each parameter: resource_id (scope to a single resource), limit (max VMs to scan, 1–100, default 50), and target (Aria target name from config). This gives the agent complete context for invoking the tool.

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

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

The description opens with "[READ] Report per-resource anomaly counts (System Attributes|total_alarms metric)", which is a specific verb and resource, and distinguishes from siblings by explaining this is the Total Anomalies metric not exposed in the UI. It clearly defines both usage modes (scoped by resource_id or scanning VMs).

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 when this tool is appropriate ('The suite-api does not expose the UI's anomalous-metrics list'), and explicitly directs to an alternative for deeper investigation ('For root cause, follow up with list_alerts(resource_id=...)'). It also gives operational advice ('keep limit modest'), but does not explicitly 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?

Even though annotations already declare readOnlyHint and openWorldHint, the description adds valuable behavioral context: the pagination envelope with fields like truncated, the need to check truncated before assuming completeness, and the impact of a DOWN collector on data freshness. It also notes that member details are enriched via an extra collectors call, giving transparency about additional underlying operations.

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

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

The description is well-structured and concise. It leads with a one-line summary, provides context in short paragraphs, and concludes with a clear Args section. Every sentence contributes to understanding, with no filler. The use of a [READ] prefix is redundant but harmless.

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

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

The description is highly complete for a list-type tool. It covers purpose, when to use, return envelope, parameter semantics, and behavioral implications. Given there is no output schema, it adequately explains output structure and pagination. It also connects to other tools in the ecosystem, making it 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?

There is only one parameter, 'target', and schema coverage is 0%. The description compensates by explaining: 'target: Aria target name from config; default when omitted.' This adds meaning beyond the schema by clarifying what the target is and its default behavior, though it could elaborate on valid formats or how the default is resolved.

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

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

The description opens with a specific verb and resource: 'List Aria Operations collector groups and their member collector status.' This clearly states what the tool does and distinguishes it from sibling tools like list_resources or get_aria_health, which focus on different aspects of the Aria environment.

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

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

The description provides explicit 'when to use' guidance: 'Check this when resources appear missing from Aria Operations or metrics are stale.' It also references related tools (list_resources, metric tools) to explain implications of a DOWN collector. However, it does not explicitly name alternatives or offer 'when not to use' guidance, so it's clear context but lacks formal 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the paginated envelope structure, notes that total can be null, and warns to 'Check truncated before calling this the complete set.' This adds meaningful behavioral detail that annotations don't cover.

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: purpose, return envelope, then args. Every sentence earns its place, with no fluff. It is front-loaded with the core action and uses a clean Args block for parameter details.

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

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

For a list operation with no output schema, the description covers all necessary context: what the tool does, how to use results (generate_report), the return envelope, and all parameters. Annotations cover safety, so no further disclaimers are 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?

Schema description coverage is 0%, so the description carries full responsibility. It does so excellently: name_filter is described as 'Substring filter on report name (case-insensitive)', limit includes range and default, target is explained as 'Aria target name from config; default when omitted.' This fully compensates for missing schema descriptions.

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

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

The description clearly states 'List available report definition templates in Aria Operations' with a specific verb and resource. It distinguishes itself from sibling tools by mentioning 'templates' and linking to generate_report, so an agent knows this is for definitions, not generated reports.

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 downstream usage guidance: 'Pass a returned id to generate_report to run one.' It implies when to use this tool (when you need templates) but doesn't explicitly contrast with list_reports or list_alert_definitions, so it lacks explicit when-not-to-use guidance.

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

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

Beyond the read-only and open-world annotations, the description discloses pagination behavior, the shape of the response envelope, the meaning of 'truncated', and the nuance that 'total' may be null. It also warns to check truncated before assuming completeness, providing valuable behavioral context that annotations do not fully cover.

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-line summary, a concise pagination note, and a clear Args list. Every sentence adds value without redundancy. It is front-loaded with the core purpose and provides details in an orderly manner.

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

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

With no output schema, the description adequately explains the return envelope. It covers purpose, parameters, pagination, the relationship to get_report, and the caveat about truncated sets. Given the tool's moderate complexity (3 optional params, paginated response), this description 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?

Schema coverage is 0%, so the description carries full responsibility. It explains all three parameters: definition_id as an optional report definition UUID, limit with a range (1–200) and default, and target as an Aria target name from config. This greatly adds meaning beyond the bare schema types and defaults.

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

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

The description clearly states the tool lists generated reports with optional filtering by report definition. It distinguishes itself from siblings by explicitly pointing users to get_report for status and download URLs, and the name 'list_reports' differentiates from generate_report, delete_report, and list_report_definitions.

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

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

It provides context for when to use this tool: to list generated reports, filter by definition, and then use get_report for details. While it doesn't explicitly say 'use list_report_definitions for definitions,' the phrase 'generated reports' and the mention of get_report imply the distinction. It also gives a practical tip to check truncated before treating the result as complete.

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

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

Annotations already indicate read-only and idempotent behavior, and the description adds valuable context beyond that: it documents the paginated return envelope (items, returned, limit, total, truncated, hint) and instructs to check `truncated` before treating results as complete. This gives the agent important operational knowledge without contradicting annotations.

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

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

The description is well-structured and concise: a clear purpose statement, a brief return-envelope note, and a short Args list. Every sentence contributes value, with no redundant or filler content, and the most important usage guidance is front-loaded in the first 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 list tool with no output schema and 4 optional parameters, the description covers the purpose, usage sequence, pagination details, and all parameter semantics. It is sufficiently complete for an agent to correctly select and invoke the tool without needing extra 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 0% schema description coverage, the description fully compensates by explaining each of the 4 parameters: resource_kind with examples, limit with default and pagination behavior, name_filter with case-insensitive substring semantics, and target as an optional config name. This adds meaning well beyond the schema's property 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 clearly states 'List resources in Aria Operations filtered by kind' and specifies the resource type examples. It distinguishes the tool from siblings by positioning it as the entry point ('Start here') and mentioning get_resource for detail, making its purpose and scope unambiguous.

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

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

The description gives explicit usage guidance: 'Start here' to convert a name/kind into a UUID, then 'call get_resource for detail on one row.' This establishes a clear workflow and differentiates when to use this tool versus get_resource for follow-up detail.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior, but the description adds substantial behavioral detail beyond this: warm-up returns None, per-VM API cost, pagination envelope with 'truncated' flag, and null total when API reports no size. These are non-obvious behaviors the agent must know.

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 bit long but well-structured: starts with a clear summary, provides warnings, return envelope info, and an Args block. Every sentence adds value, though some redundancy exists (e.g., 'One stats call per VM' could be merged into the performance warning). Overall it earns its length.

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

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

Despite no output schema, the description explains the return envelope (items, returned, limit, total, truncated, hint) and the critical 'truncated' check. Combined with annotations, it covers purpose, usage, behavior, params, and return semantics. The tool is complex enough (pagination, warm-up, per-VM calls) that this completeness is necessary.

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 explain params. It does so in a dedicated 'Args' section, explaining resource_id as optional VM resource UUID scope, limit as 1-100 with default 50, and target as config-based. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool's purpose: 'List VM rightsizing data — recommended CPU/memory size per VM.' It also specifies the data source (OnlineCapacityAnalytics recommendedSize metrics) and that it's a read operation. This distinguishes it from sibling tools like list_resources or get_capacity_overview.

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 usage context: 'Compare against the VM's provisioned size to find over/under-provisioning', warns about warm-up time ('Values are None while capacity analytics warm up'), and advises on performance ('One stats call per VM — keep limit modest'). It also directs users to get UUIDs from list_resources. However, it doesn't explicitly name alternative tools or when not to use this tool, making it clear but not fully 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, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations, such as the paginated envelope format (items, returned, limit, total, truncated, hint) and the explicit warning to check 'truncated' before treating it as a complete set.

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 [READ] prefix, a one-line purpose, a concise explanation of the return envelope, and a clear Args section. Every sentence contributes necessary information, especially given the lack of schema descriptions.

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 tool's purpose, usage context, parameter semantics, and return envelope. It is sufficiently complete despite no output schema, and the caveat about the 'truncated' flag ensures the agent understands the data model.

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 has 0% description coverage, so the description fully compensates by explaining each parameter: name_filter (substring, case-insensitive), resource_kind (e.g., VirtualMachine, HostSystem), limit (1–500, default 100), and target (Aria target name). This is essential and precisely stated.

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

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

The description begins with a clear, specific statement: 'List symptom definitions', using a specific verb and resource. It further clarifies the purpose by noting the returned IDs are used when calling create_alert_definition, distinguishing it from sibling tools like list_alert_definitions.

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 contextual usage: it is a READ operation for fetching symptom definitions to be used with create_alert_definition. This implies when to use it, though it does not explicitly state exclusions or 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?

Annotations already provide readOnly, idempotent, and non-destructive hints, so the burden is lower. The description adds valuable context: the base path is inferred and every result carries base_path_confirmed=False until confirmed, plus an actionable error when the integration is missing. This goes 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 moderately sized but well-structured: opening summary, usage context, gotcha, then Args list. Each sentence adds value. Slight redundancy in the Args list mirroring schema parameter names, but the added descriptions justify its length.

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

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

For a 5-param tool with no output schema, it covers the main areas: return format (result series, timestamp, value, paginated envelope, result_type/status), a dangerous gotcha (base_path_confirmed=False), and prerequisites. It could elaborate on pagination specifics, but given no output schema, this is sufficiently complete for an agent to invoke.

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 carries full responsibility for parameters. It explains each of the 5 args: query is a PromQL expression, time is RFC3339 or Unix seconds, source_id scopes the query, limit has a default and None behavior, target is a config name. This adds meaning beyond the bare schema.

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

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

The description clearly states 'Run a real-time PromQL instant query' with a specific verb and resource. It distinguishes from sibling get_resource_metrics by positioning it as complementary for near-real-time metrics, making the tool's purpose unique.

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

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

Explicitly tells when to use ('for near-real-time (~2s) metrics') and names the alternative (get_resource_metrics for historical rollups). It also mentions a prerequisite (VODAP integration registered). It lacks an explicit 'do not use when' statement, so not 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 indicate a non-readonly, non-destructive operation. The description adds that the operation is reversible, returns the action taken, and clarifies the effect of disabling vs deleting. This goes beyond the annotation hints.

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

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

The description is compact, front-loaded with the purpose, and includes essential return information and parameter details in a structured list. No redundant or extraneous content.

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

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

The description covers the tool's purpose, usage context, parameter semantics, return values, and relationship to a sibling tool. With no output schema, it appropriately explains the return values. This is complete for a simple state-toggle tool.

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

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

Schema has no parameter descriptions (0% coverage), but the description provides meaningful explanations for all three parameters: definition_id sourced from list_alert_definitions, enabled as a boolean toggling, and target with a config default. 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 states a specific verb+resource: 'Enable or disable an existing alert definition.' It also distinguishes from delete_alert_definition by noting the reversible vs irreversible action, making the purpose unambiguous.

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

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

Explicitly instructs to use this tool instead of delete_alert_definition for silencing, because disabling is reversible and deleting is not. This gives clear when-to-use guidance and names the alternative.

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