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

Goes well beyond the annotations by describing the underlying HTTP mapping, the resulting control state ASSIGNED, the persistence of the alert's active status, and the preview behavior when confirmed=False. This adds concrete behavioral context that the annotations alone do not provide.

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

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

Every sentence carries useful information: core action and effect, technical endpoint mapping, usage guidance versus cancel_alert, and confirmed-flag behavior. It is front-loaded and has 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?

The description fully explains the state transition, the endpoint, and the alternative, and it touches on the preview response. Since there is no output schema, a mention of the exact return structure would improve completeness, but the description is still adequate for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the confirmed flag's preview behavior but does not add any parameter-specific details beyond what the schema already documents.

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

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

Description states a specific verb 'acknowledge' and resource 'active alert', immediately clarifying it means taking ownership and not cancelling. It also explicitly maps to POST /alerts?action=takeownership, which leaves no ambiguity about the operation.

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

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

Explicitly tells the agent when to use this tool ('Use this when you want to own the alert without closing it') and names cancel_alert as the alternative that closes the alert for good. It also explains the confirmed flag's role in previewing versus actually making the change.

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

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

Annotations already mark this as destructive, but the description adds important context: cancellation is permanent, cancelled alerts will not re-trigger unless the underlying condition recurs, and confirmed=False only previews without making changes. This goes well beyond the structured annotation data.

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 core action, and every sentence earns its place: action, permanence, alternative, re-trigger behavior, and preview behavior. There is 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?

For a three-parameter destructive tool with full schema coverage, the description covers what the tool does, when to use an alternative, the permanence of the action, re-trigger semantics, and the preview mechanism. No critical operational detail is missing.

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

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

Schema description coverage is 100%, so the input schema already documents alert_id, target, and confirmed well. The description reinforces the confirmed preview behavior but does not add substantial new parameter-level meaning beyond what the schema provides.

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 and resource ('Cancel (dismiss) an active alert') and clearly distinguishes itself from acknowledge_alert by noting the difference between dismissing and marking as seen. An agent can tell exactly what this tool does and how it differs from its closest sibling.

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

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

It explicitly tells the agent to use acknowledge_alert instead when only marking as seen, and explains when cancellation is appropriate. It also clarifies the confirmed parameter behavior, giving clear operational guidance for when to actually execute versus preview.

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

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

Annotations already establish that this is a write operation, non-idempotent, and non-destructive. The description adds useful behavioral context by stating the return value ('Returns the new definition's id and name') and by requiring that symptom definitions already exist before calling.

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

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

Three tightly packed sentences with no filler. The main purpose is first, followed by return value, then prerequisite and alternative routing. Every sentence contributes to correct tool selection or invocation.

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 7-parameter create operation with no output schema, the description covers the essential missing context: what it creates, what it returns, what must be done beforehand, and which sibling to use instead. The remaining parameter details are fully covered by the schema.

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

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

Schema coverage is 100%, so all parameters are already described. The description adds practical value beyond the schema by telling the agent to call list_symptom_definitions first for symptom_definition_ids, which directly informs how to populate a required parameter.

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

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

The description opens with a specific verb and resource: 'Create a new alert definition referencing existing symptom definitions.' It clearly distinguishes this from the sibling set_alert_definition_state by explicitly warning not to create a variant just to silence an 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 when-to-use guidance: run list_symptom_definitions first to obtain valid symptom_definition_ids, and use set_alert_definition_state instead when the goal is to silence an existing definition. This is actionable and prevents misuse.

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 and readOnlyHint=false, the description reveals important behavioral consequences: active alerts generated by the definition are not affected, and confirmed=False provides a preview without mutating state. This is exactly the kind of context annotations alone do not 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?

Four short sentences, each carrying meaningful information: the irreversible action, the non-impact on active alerts, the safer alternative, and the preview default. No filler or repetition, and the destructive nature is front-loaded.

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

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

For a destructive tool with a confirmation parameter, the description is fully complete: it tells the agent what is deleted, why to prefer an alternative when uncertain, and how to preview before committing. With no output schema required, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds semantic value by explaining the confirmed=False preview behavior, which recontextualizes the confirmed parameter's role. target remains only schema-documented, but that is acceptable given its simple default behavior.

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 ('delete') and resource ('alert definition'), and immediately clarifies permanence: 'Permanently delete... Irreversible.' It also distinguishes itself from the sibling set_alert_definition_state by explicitly positioning that as the non-destructive alternative.

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

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

The description explicitly tells the agent when NOT to use this tool: use set_alert_definition_state(enabled=False) instead to silence a definition that may later be needed. It also explains the confirmation flow, making the intended usage pattern 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?

The description goes well beyond the annotations by disclosing that deletion is irreversible, is recorded in the audit log, returns an error for invalid report_id, and defaults to a non-destructive preview unless confirmed=True. It also clarifies exactly what is and is not removed, which is critical for a destructive operation.

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

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

The description is dense but every sentence adds essential information: what is deleted, what survives, irreversibility, audit logging, error behavior, and the preview default. The [WRITE] prefix and front-loaded main action make it easy to scan.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers the critical operational context: preconditions (list_reports), consequences (permanent deletion, audit log), and safety mechanism (confirmed flag). An agent has enough information to invoke it correctly and understand the side effects.

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

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

The input schema already describes all three parameters with full coverage, including the confirmed flag and report_id semantics. The description reinforces these details (e.g., confirmed=False means preview, report_id must be a valid UUID) but does not add substantial new parameter-level meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Permanently delete a generated report artifact from Aria Operations.' It distinguishes the report instance from the report definition and schedules, which differentiates this from sibling tools like delete_alert_definition and get_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 provides explicit guidance: use list_reports to find valid UUIDs first, use generate_report to recreate the artifact, and note that confirmed=False only previews the deletion. This clearly communicates when and how to invoke the tool versus alternatives.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds useful behavioral details: filters are comma-separated, omitted filters match all, and results arrive as finding summaries in a paginated envelope. This gives the agent a realistic expectation of output shape without contradicting the annotations.

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

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

The description is compact and front-loaded: the first sentence states the action and resource, the next gives usage context, then filter behavior, return shape, and a useful compliance disclaimer. Every sentence earns its place, and there is no redundant restatement of schema fields.

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

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

For a read-only list tool with no output schema, the description does a good job: it names the returned fields, mentions pagination, and explains filter semantics. The main gap is that the paginated envelope is not further described (e.g., how to request subsequent pages), but the optional limit parameter and schema already cover enough for a first invocation.

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

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

The schema already covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds semantic value by explaining the shared filter convention ('comma-separated strings; omit a filter to match all') and states what the returned summaries contain, which helps the agent reason about how the optional filters map to results. This exceeds the baseline.

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

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

The description opens with a specific verb-resource pair — 'List Operations diagnostic findings' — and clarifies the domain by naming example content ('misconfigurations, health rule hits') and the returned summary fields. It also explicitly distinguishes this tool from compliance benchmark results, which prevents confusion with a closely related category. The purpose is unambiguous even without sibling-specific comparison.

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 clearly when to use the tool ('review current diagnostic findings') and gives an explicit exclusion ('NOT compliance benchmark results') with a routing suggestion to vmware-harden. However, it does not contrast this tool with nearby siblings such as list_alerts, list_anomalies, or investigate_alert, leaving some alternative-selection work to the agent.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only: it does not renew or replace any certificate.' It also goes beyond annotations by disclosing the return envelope and the defensive field-reading gotcha, which is genuinely useful behavioral information.

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

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

The description is compact and efficiently organized: purpose, use case, return format, read-only caveat, and a practical gotcha are each covered in distinct, information-dense sentences. There is no filler or repetition of schema 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?

For a read-only list tool with two optional parameters and no output schema, the description fully prepares an agent: it names the returned summary fields, the pagination envelope, the read-only nature, and a real behavioral caveat. Nothing essential for invoking the tool is missing.

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

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

Schema description coverage is 100% and both parameters, limit and target, are already fully documented with defaults and meaning in the input schema. The description adds no new parameter-level guidance, so the baseline score of 3 is appropriate.

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

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

The opening sentence, '[READ] List certificate status and expiry across the VCF fleet', states a specific verb, resource, and scope. It is clearly about certificates across VCF components, which is distinct from alert, finding, and resource siblings, though it does not explicitly name an alternative or say what falls outside its 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?

'Use this to spot certificates that are expired or expiring soon across all VCF components managed by Operations 9.1' gives an explicit, concrete selection condition. It does not mention when not to use it or point to an alternative such as a renewal tool, but for a listing tool the usage context is clear.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the paginated return envelope, the exact domain summary fields, the meaning of configuration_state values, the 404 behavior for a wrong integration_id, and the critical 'note' gotcha where an empty list means UNKNOWN rather than no domains. This is rich behavioral disclosure that significantly helps an agent interpret results 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 dense but every sentence earns its place: intent, source of the required parameter, return fields, error semantics, and the critical empty-list gotcha. The '[READ]' prefix and front-loaded purpose make scanning easy, and there is no redundant filler.

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

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

With no output schema, the description fully compensates by enumerating the returned fields, status values, pagination behavior, and error cases. It also warns about the ambiguous empty-response case, which is exactly the kind of contextual information an agent needs to avoid misreporting results.

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 already documents all three parameters with 100% coverage, so the baseline is 3. The description adds valuable context for integration_id by pointing to the exact UI location for the UUID and explaining the 404 meaning, going beyond the schema's 'UUID of the registered VCF integration'.

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 '[READ] List the SDDC/workload domains behind one registered VCF integration', using a specific verb and resource. It clearly distinguishes this tool from siblings like fleet_certificate_list and fleet_password_account_list by scoping it to VCF integration domains, so an agent can select it without ambiguity.

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

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

The description explicitly says 'Use this to enumerate the domains of a VCF integration registered in Operations' and explains that the integration_id must be supplied by the operator because 'this skill does not list VCF integrations'. It provides clear context and a practical exclusion, though it does not name alternative tools for when this tool is not appropriate.

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

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

Beyond annotations, the description discloses the return payload shape (username, resource, status, expiry, last_rotated), the paginated envelope, and a defensive-read behavior where unknown fields degrade to empty. It also reinforces the readOnlyHint by explicitly stating the rotation endpoint is not wired in. Nothing contradicts the annotations.

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

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

The description is compact, front-loaded with a clear summary, and each sentence serves a distinct purpose: scope, usage, returns, safety, and a gotcha. No filler or repetition; the operational caveat about defensive field reading is valuable and earns its place.

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

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

Considering there is no output schema, the description does a good job by naming the returned per-account fields and mentioning pagination. It could specify pagination mechanics in more detail, but with only two optional parameters and full schema coverage, an agent has enough to call the tool correctly. Minor gaps are acceptable here.

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

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

Schema coverage is 100%, and both parameters have meaningful descriptions: limit defaults to 50 and None returns all; target selects the config target. The description's mention of the paginated envelope is related to limit but adds little beyond what the schema documents, so the baseline of 3 is appropriate.

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

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

The first sentence states the exact scope and action: 'List managed password-account status across the VCF fleet.' It clearly identifies the resource (password-account status), distinguishes it from sibling list tools like fleet_certificate_list and fleet_domain_list, and is not a tautology.

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

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

The description explicitly says when to use it ('Use this to review which fleet accounts Operations manages and their rotation/expiry status') and even gives a when-not: it never rotates or sets a password, and the rotation endpoint is deliberately not wired in. It does not explicitly name alternative tools, but the context and sibling list make the tool's niche 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 signal readOnly=false, idempotent=false, and destructive=false. The description adds crucial context beyond those flags: the tool returns immediately with a report_id and PENDING status, does not wait for the file, and requires polling. This is exactly the behavioral nuance an agent needs and cannot infer 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?

Two compact, well-structured sentences. The first states purpose, and the second explains the async workflow and follow-up action. No filler or redundant repetition of the schema.

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

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

With no output schema, the description fully explains what the tool returns (report_id, PENDING status) and how to complete the workflow (poll get_report until COMPLETED, then use download_url). For an async trigger tool with rich schema descriptions, this is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description adds no parameter-level detail; however, the schema itself provides rich guidance (resource_ids first-ID semantics, list_resources, definition_id via list_report_definitions). Note a minor schema inconsistency: resource_ids is declared optional but its description says 'REQUIRED', which could confuse agents, but this is not a failure of the main description.

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

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

The description clearly states the operation ('Trigger generation'), the resource ('a report from a report definition template'), and the asynchronous behavior. The [WRITE] tag and the focus on generation distinguish it from read-oriented siblings like get_report and 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 explicitly tells the agent how to use the tool and what to do next: poll get_report(report_id) until status == COMPLETED, then use download_url. It implies the division of labor between generation and retrieval, though it does not explicitly state when not to use 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, idempotentHint, and destructiveHint=false, but the description adds crucial behavioral context: the symptoms_note gotcha (empty list may mean UNKNOWN rather than no symptoms), the Alert model's lack of a resource name, and that recommendations hang off the definition. These are non-obvious behaviors that prevent incorrect agent reasoning.

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

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

Every sentence earns its place: purpose, usage ordering, response fields, the symptoms_note gotcha, resource-name resolution, recommendations location, and follow-up actions. The description is dense but front-loaded with the core action and contains no redundant or filler content.

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

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

With no output schema, the description fully specifies the return object's fields and caveats, including the edge case of symptoms_note. It also covers what the tool cannot do (resolve resource name, provide recommendations) and directs to the appropriate siblings. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The schema already documents alert_id as 'The alert UUID (from list_alerts)' and target as a config name with a default. The description adds no new parameter semantics beyond reinforcing that alert_id is a UUID; it does not compensate beyond the schema.

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

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

Description states a specific verb and resource: 'Get full details for one alert by UUID, including its contributing (triggered) symptoms.' It clearly distinguishes this from list_alerts (discovery/filtering) and investigate_alert (correlation), so an agent knows exactly what this tool does and what it does not do.

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

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

The description explicitly says 'Use this after list_alerts to drill into a single alert; use list_alerts to discover or filter them.' It also names investigate_alert as an alternative for one-step correlation and acknowledge_alert/cancel_alert for acting on the alert, giving clear when-to-use and 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?

Annotations already mark the tool as read-only and idempotent, and the description adds meaningful behavior not inferable from schema: a 503 from the platform is converted to OFFLINE and never raised, so the tool answers even when Aria is down. It also discloses what overall_status represents and names the returned fields.

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

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

The description is compact and front-loaded with the tool's purpose and return values, followed by essential usage context and error-handling behavior. Every sentence adds value without redundancy.

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

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

The description is complete for a simple health-check tool: it explains the meaning of the status, the return fields, the 503 handling, and the relationship to a sibling tool. Even though there is no output schema, the description provides enough return-value detail for an agent to use the result correctly.

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

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

Schema description coverage is 100%, so the schema already explains the optional target parameter. The description does not add further parameter-level details, but none are necessary given the high schema coverage.

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

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

The description clearly states the tool checks Aria Operations platform node status and explicitly defines the ONLINE/OFFLINE outcome semantics. It is distinct from sibling tools by focusing on platform-level health rather than alerts, resources, or collectors.

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

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

The description explicitly says to use it to verify Aria Operations is functioning before investigating monitoring blind spots, and notes that per-service breakdown is not exposed by the public API. It also gives a concrete next-step alternative: check list_collector_groups when status is ONLINE but data looks stale.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral detail beyond annotations: it notes that values are None while capacity analytics are warming up on a fresh instance, and it identifies the data source (OnlineCapacityAnalytics metrics). This is useful non-obvious context.

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

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

The description is appropriately sized for the tool's complexity and front-loads the core action and outputs in the first sentence. The caveat about warming up and the sibling routing guidance each earn their place. No filler or repetitive content 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?

There is no output schema, so the description carries the burden of explaining return semantics. It covers the key values (capacity_remaining_pct, per-dimension absolute remaining, days-until-full), the warm-up None behavior, and the data source. Given the simplicity of the input parameters and the annotations, the description is complete enough for correct selection and invocation.

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

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

Schema description coverage is 100%, and both parameters already have descriptions: cluster_id is 'The cluster resource UUID (ClusterComputeResource, from list_resources)' and target has a default and config-origin note. The description adds little parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('Returns a capacity overview') and resource ('a cluster'), and precisely identifies the output components: group-level capacity_remaining_pct, per-dimension absolute remaining capacity, and projected days-until-full. It further distinguishes itself from sibling tools by naming what it includes and where it comes from, so an agent can clearly tell it apart from get_remaining_capacity and get_time_remaining.

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

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

The description explicitly says 'Start here when assessing overall cluster capacity health' and provides concrete alternatives for more focused needs: 'for absolute headroom values use get_remaining_capacity, and for just the exhaustion projections use get_time_remaining.' This gives the agent an unambiguous routing rule for when to use this tool versus its 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 mark the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: the output shape, per-dimension units, the OnlineCapacityAnalytics source, and the caveat that values are None while analytics warm up.

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

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

Three sentences, each earning its place: purpose, return shape and caveat, and sibling routing. The read marker is front-loaded and there is no filler.

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

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

There is no output schema, but the description covers the key returned fields, units, group-level behavior, warm-up nulls, and alternative tools. For a simple 2-parameter read-only analytics query, this is enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already fully documented. The description adds minor context about cluster/host scope and group-level percentage, but does not need to restate parameter meanings. Baseline 3 is appropriate.

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

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

The description opens with a clear read verb and resource scope: 'Get remaining capacity headroom for a cluster or host.' It also names sibling alternatives, so an agent can distinguish this from get_capacity_overview and get_time_remaining without inspecting schemas.

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

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

It states precise selection context by noting capacity_remaining_pct is only available at group level, and explicitly routes to get_capacity_overview for the combined view or get_time_remaining for projected days-until-full. This gives actionable when-to-use and alternative 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?

With annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds significant behavioral context: URLs are always constructed even when PENDING, download_url must be gated on status, completion_time has appliance-specific formatting, and title/description depend on the report definition. This goes well 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 the core purpose and then enumerates return fields and edge cases. It is somewhat long but every sentence carries useful operational detail, so the length is justified.

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, so the description carries the full burden of explaining return values. It exhaustively lists fields, statuses, null cases, time formats, and the key caveat about URLs being present before completion. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces that report_id comes from generate_report or list_reports, but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Get status and download URLs for a generated report.' It clearly identifies the tool's subject (reports) and its outcome (status and URLs), and the detailed return-field list distinguishes it from related siblings like generate_report and 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 explicitly says 'Use this to poll after generate_report', giving a clear usage context. It does not explicitly name alternatives to avoid, but the polling role and the mention that report_id comes from generate_report or list_reports sufficiently guide selection.

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

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

Annotations already convey readOnly/idempotent/non-destructive, so the description does not need to repeat that. It adds useful behavioral context beyond the annotations by detailing the shape of the returned object, the badge scoring range, and the null condition when Aria has not scored a badge. This helps the agent reason about output without an output schema.

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

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

Three dense sentences carry a lot of value: the first summarizes the return payload, the second positions the tool in a workflow and states its key limitation, and the third routes to alternatives. There is no filler, and the most decision-relevant fact (the UUID-only restriction) is front and center.

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 one required parameter and no output schema, the description fully compensates for the missing output schema by listing all returned fields and the badge structure. It also covers usage context, parameter source, and sibling alternatives. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds extra semantic value by explicitly noting that resource_id must be a UUID obtained from list_resources and that the tool 'does not accept a name,' which prevents callers from passing a human-readable identifier. This is meaningful clarification beyond the schema description.

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

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

The description opens with a clear verb and resource: 'Returns one resource object', then enumerates the exact fields returned so an agent knows what to expect. It explicitly distinguishes itself from get_resource_health and get_resource_metrics, making it easy to tell apart 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?

It states exactly when to use it: 'Use this after list_resources to inspect a single UUID in depth', and gives an explicit exclusion: 'it does not accept a name, so use list_resources to discover UUIDs by kind or name.' It also names the specific sibling tools for badge-only or time-series needs, leaving no ambiguity about routing.

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

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

Beyond the readOnly/idempotent annotations, the description discloses return source (badges[] array), score range (0–100), and the critical null/-1 semantics indicating a badge was not computed rather than being healthy. This is valuable behavioral context an agent could not infer from the schema or annotations alone.

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

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

The description is compact and front-loaded. It communicates purpose, return behavior, score semantics, and alternatives in three sentences with 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?

For a read-only two-parameter tool with full schema coverage and annotated safety hints, the description provides enough information about return values and edge cases (null/-1) to call the tool correctly without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents resource_id and target. The description adds no new parameter-level detail beyond confirming the resource context, but it also does not need to; baseline 3 applies.

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

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

The description states a specific verb and resource: 'Get the health, risk, and efficiency badge scores for a resource.' It also clarifies what is returned (three scores and their colors) and distinguishes this tool from siblings like get_resource and list_alerts.

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

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

Explicit guidance is provided: 'Use this when the scores are all you need; use get_resource for the whole object, or list_alerts(resource_id=...) for what drove a low score.' This directly routes the agent to the correct tool based on need.

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 safety, so the description adds useful behavior beyond them: the exact return shape (dict keyed by metric key) and the important missing-key behavior. This is meaningful context that affects how an agent interprets results.

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

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

Three dense sentences with no filler. The purpose is front-loaded, followed by return shape, usage guidance, and a critical data-interpretation caveat. Every sentence earns its place.

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

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

With no output schema, the description must explain return values, and it does: dict keyed by metric key, list of {timestamp_ms, value} points, and absence behavior. Combined with full schema coverage and rich annotations, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including examples and defaults. The description adds no significant parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch time-series metric statistics for a resource') and explicitly distinguishes itself from get_resource_health. The 'not an envelope' return shape note further clarifies what the tool does.

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

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

Gives explicit when-to-use guidance: 'Use this for history; for a single current score use get_resource_health instead.' It also adds operational guidance about checking which keys came back before reporting a metric as zero.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context by specifying the return fields risk_score and risk_color, the null behavior when Aria has not computed a badge, and the limitation that the badge does not explain what is wrong. This goes beyond the annotations and gives the agent useful behavioral expectations.

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, front-loading the core purpose and using short, information-dense sentences. It covers purpose, return values, usage guidance, null cases, and alternatives 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-only tool with one required parameter and no output schema, the description fully covers what an agent needs: what the score means, what fields are returned, when the value is null, and which sibling tool to use for more detail. The annotations and schema handle the remaining context.

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

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

Input schema coverage is 100%, so the schema already documents resource_id as 'The resource UUID' and target as the Aria target name. The description does not add significant parameter-level meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get the risk badge score for a resource', which clearly identifies the operation. It also distinguishes itself from the sibling get_resource_health by noting it returns only the risk number, not health and efficiency.

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

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

The description explicitly states when to use this tool: 'Use this when the risk number is all you want.' It also names the alternative get_resource_health and provides a use-case boundary, and directs users to list_alerts when they need contributing alerts, covering both when-to-use and when-not-to-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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description's [READ] prefix reinforces without contradiction. Beyond annotations, the description adds two valuable behavioral disclosures: the output is structured per dimension (cpu, mem, diskspace) and the crucial 'None does not mean unlimited' warm-up caveat, which prevents a likely misinterpretation. It stops short of 5 by not covering error or edge-case behavior, but the additions are meaningful.

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

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

Four sentences, each earning its place: purpose, return structure, sibling routing, and the None caveat. The [READ] tag and primary purpose are front-loaded. Slightly more verbose than strictly necessary, but no wasted 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?

With no output schema, the description correctly carries the burden of explaining return values (per-dimension projected days until full) and covers the warm-up None case. Simple parameters are fully documented in the schema, annotations cover safety, and sibling routing is present. An agent has what it needs to select and invoke this 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 100% — both resource_id ('The resource UUID (typically ClusterComputeResource)') and target ('Aria target name from config; default when omitted') are already documented. The description adds no parameter-level detail beyond the implicit mapping of 'cluster' to resource_id, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Predict when a cluster will exhaust its capacity based on usage trends') and names the return value (time_remaining per capacity dimension). It explicitly differentiates from get_capacity_overview ('this tool returns only the projections'), so an agent can distinguish it from siblings without opening schemas. The [READ] prefix also signals operation type.

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 an explicit routing rule: 'Use get_capacity_overview instead when you also want current headroom — this tool returns only the projections.' This states both the condition and the alternative, leaving no inference needed. The sibling context confirms get_capacity_overview is the right comparison tool.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the paginated envelope fields, the null total behavior, and the critical truncated caveat. This tells the agent that a returned result may be incomplete and to check truncated before trusting the full 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 compact, front-loaded with the primary purpose, and uses a second sentence for essential result handling. Every sentence contributes useful information without 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?

There is no output schema, so the description compensates by specifying the return envelope and truncation behavior. With read-only annotations, four fully documented optional parameters, and a clear follow-up via get_resource_metrics, an agent has enough context to call and interpret this 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 100%, so the schema already documents all four parameters. The description adds only general mapping like 'given metric' to metric_key and resources to resource_kind, but no additional parameter semantics beyond the schema.

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

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

The description names a specific operation: query resources with the highest consumption of a given metric. It also distinguishes itself from get_resource_metrics by positioning that sibling as a follow-up for history. The [READ] prefix is consistent and makes intent obvious.

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

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

The description gives clear context for when to use this tool: when you need top consumers of a metric. It also points to get_resource_metrics for the next step, but it does not explicitly state when NOT to use this tool or mention alternatives like list_resources.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds significant behavioral context: it performs server-side correlation, returns five always-present keys, degrades unresolvable resources to warnings plus nulls rather than errors, and warns against matching inventory unless confirmed. This goes well beyond the 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 front-loaded with the primary purpose, then structured into what it does, what it returns, and gotchas. It is detailed because the tool has no output schema, but every sentence carries meaningful information and none are filler.

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

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

With no output schema, the description fully compensates by enumerating the five always-present return keys, the null behavior, the next_step guidance, and warning behavior. It covers edge cases and the most common misuse, making the tool self-contained for correct invocation.

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

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

The input schema already documents alert_id as "The alert UUID from list_alerts (not the resource UUID)" and covers target with its default, so schema coverage is 100%. The description's gotcha restates this emphasis rather than adding genuinely new parameter semantics, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: "Resolve one alert to its affected resource in a single call." It clearly distinguishes itself from chaining get_alert and get_resource, which are sibling tools, so an agent can tell exactly what this tool does and what it replaces.

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

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

It explicitly says to use this tool "instead of chaining get_alert then get_resource by hand," naming the exact alternatives and the condition favoring this tool. The gotchas also instruct where alert_id comes from and when correlation.confirmed must be true before matching against vCenter inventory.

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 it read-only, idempotent, and non-destructive, and the description adds valuable behavior beyond that: criticality is derived from states[], there is no top-level criticality/enabled field, pagination uses a specific envelope, limit out-of-range is rejected rather than clamped, and truncated should not be looped on. This is exactly the kind of non-obvious behavior agents need.

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

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

The description is long but every sentence carries operational value: purpose, model quirk, pagination envelope, exact paging rules, and a warning against a common loop. It is front-loaded with the [READ] signal and the core purpose before diving into 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 read-only list tool with no output schema, the description fully covers the return envelope, pagination contract, edge cases, and how the results connect to sibling tools. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaningful pagination semantics for limit, offset, and next_offset beyond the schema, including the rejection behavior for out-of-range limits and the instruction to stop when next_offset is null.

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

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

States a specific verb ('List') and resource ('alert definitions') and clarifies they are templates that generate alerts when triggered. It also distinguishes the returned ids' use from the sibling set_alert_definition_state, so the tool's role is unambiguous.

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

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

The description gives clear operational guidance: use a returned id with set_alert_definition_state, and explains pagination semantics precisely. It does not explicitly contrast with create/delete/list siblings, but the usage context is strong enough to guide selection.

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

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

Annotations already mark this as read-only, idempotent, and open-world. The description goes well beyond that by documenting pagination semantics, the exact meaning of truncated, the behavior of next_offset (pass back and stop when null), and the warning not to loop on truncated. It also reveals that the Alert model lacks a resource name, which is critical 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?

Every sentence adds value. The description is structured with a one-line purpose, a return-format summary, and a dedicated pagination walk-through. It is detailed without redundancy, and the most important caveats are front-loaded.

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

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

With no output schema, the description must explain the response shape and pagination protocol, and it does so thoroughly. It covers the envelope fields, the truncated trap, and the cross-reference to get_resource. For a list operation with six optional parameters, this is complete enough for an agent to call and page 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?

Although schema coverage is 100%, the description adds essential parameter behavior: limit is rejected (not clamped) outside 1-500, offset is an absolute skip count, next_offset must be passed back as offset, and the walk stops on null. This is practical, non-obvious semantics that the schema alone does not convey.

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 alerts from Aria Operations.' It clearly distinguishes list_alerts from siblings like list_alert_definitions, get_alert, and investigate_alert by focusing on alert summaries rather than definitions or single-alert lookup.

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

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

The description clearly scopes the tool's use case and even directs follow-up resource-name resolution via get_resource. It does not explicitly enumerate when not to use this tool, but the purpose is distinctive enough among siblings and the 'List alerts' phrasing makes the intended context unmistakable.

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, idempotentHint, and destructiveHint false, the description adds critical behavioral detail: limit bounds the answer but not the scan, the whole inventory is read in bulk pages, and scan_complete/truncated semantics reveal when results may be partial. It goes well beyond annotation coverage and explains real-world edge cases like a short list not proving a clean environment.

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?

Though lengthy, the description is tightly structured with a READ marker, context, parameter behavior, and output envelope explanation. Every sentence contributes necessary operational knowledge, and the most important purpose statement is front-loaded. The length is justified by the tool's non-obvious scan/ranking behavior.

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

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

With no output schema, the description fully documents the paginated response envelope and the meaning of each field, including returned, limit, total, truncated, hint, scanned, vm_total, and scan_complete. It also covers the partial-scan caveat and explains why a short result list is not sufficient evidence of cleanliness. Nothing critical is missing for an agent to call this correctly.

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

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

Schema coverage is 100%, but the description substantially enriches parameter meaning. It explains the resource_id branching behavior, clarifies that limit is a result bound rather than a scan bound, and notes that out-of-range limits are rejected. This adds genuine semantic value beyond the schema's already-good 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?

Description states a precise verb and resource: 'Report per-resource anomaly counts' via the Total Anomalies metric. It clearly distinguishes itself from the UI's anomalous-metrics list and from list_alerts, which is for root cause follow-up. An agent can tell exactly what this tool computes.

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 mode-based guidance: with resource_id it returns that resource's count, without it ranks all VMs and returns the worst limit. It also names list_alerts as the follow-up tool for root cause, providing an alternative routing decision. This is strong, actionable usage guidance.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: it discloses the pagination envelope fields, notes that total is null when the API reports no size, warns to check truncated, and explains the enrichment via one extra collectors call. 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 and front-loaded: purpose, context, usage trigger, behavioral caveats, and return format. Every sentence adds value, and the pagination warning is placed at the end without clutter.

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

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

The tool is simple (one optional parameter, no required inputs, no output schema), but the description still covers the key operational concerns: when to use it, what groups contain, what a DOWN collector implies, and what the paginated response looks like. Nothing essential is missing.

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

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

The schema already fully covers the single parameter with a clear description: 'Aria target name from config; default when omitted.' Since schema description coverage is 100%, the description doesn't need to add parameter details. It adds no new parameter semantics but is not deficient.

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.' It also explains what collectors are and links the tool to symptoms (missing/stale resources), making its purpose distinct from siblings like list_resources and get_resource_metrics.

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

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

The description explicitly says when to use this tool: 'Check this when resources appear missing from Aria Operations or metrics are stale.' It also explains how a DOWN collector affects list_resources and metric tools, which is a clear usage signal. It doesn't name alternatives to rule out, but the context is sufficiently 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?

The description discloses important runtime behavior beyond the annotations: the exact pagination envelope shape, that truncated indicates page incompleteness and stays true on the last page, that limit values are rejected rather than clamped, and that total can be null. This gives an agent accurate expectations without invoking the tool.

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 organized into three focused paragraphs: purpose/workflow, return envelope, and pagination walk. Every sentence adds essential information about a non-trivial paginated endpoint. No filler or repetition.

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

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

With no output schema, the description fully compensates by documenting the response envelope, null total, truncated flag, and next_offset semantics. It also covers the key edge cases (limit rejection, stop condition, don't loop on truncated). The tool is complex, and the description is complete enough for correct invocation and response interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the meaning of limit and offset by explaining the rejection behavior, the skip semantics, and the next_offset handshake. It does not add detail about name_filter or target, but those are already well-described in the schema, so the additional value warrants a 4.

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

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

The description clearly identifies the verb ('List') and resource ('available report definition templates in Aria Operations'), and distinguishes the tool from the sibling generate_report by stating that returned ids are passed to it. The term 'definition templates' also differentiates it from list_reports, which presumably lists 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 explains the intended workflow: list definitions, then pass an id to generate_report. It also provides detailed pagination usage instructions, including how to use next_offset and when to stop. It does not explicitly state 'use this instead of list_reports', but the workflow context makes the primary use case clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavior: the paginated envelope shape, total possibly null, the meaning of truncated, and the critical caveat that there is no offset so truncated pages cannot be walked past. This is exactly the kind of non-obvious behavior an agent needs to 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 front-loaded with purpose and the get_report routing, then packs the essential pagination behavior into a second dense but efficient paragraph. Every sentence adds meaningful information 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?

With no output schema, the description fully compensates by enumerating the response envelope fields and the truncation semantics. It also covers the tool's relationship to get_report and the optional filter, leaving no critical gap for an agent to call this 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 100%, so the burden on the description is low. The description adds a little context by mentioning filtering by report definition, which maps to definition_id, but it does not explain limit bounds or target beyond what the schema already provides.

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 precise verb and resource, 'List generated reports', and immediately states the optional filter by report definition. It also differentiates the tool from its sibling get_report by directing readers to use that tool for status and download URLs, making the boundary clear.

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 routing guidance, explicitly telling the agent to pass a returned id to get_report for status and download URLs. It also implies when definition_id should be used, but it does not explicitly contrast with list_report_definitions or mention when not to use this tool.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the description adds value by disclosing pagination behavior and the exact response envelope: items, returned, limit, total, truncated, and hint. The warning to 'check truncated before calling this the complete set' is useful behavioral context beyond the schema.

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

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

The description is compact and front-loaded with the most important guidance: this is a read operation and the entry point for UUID resolution. Every sentence earns its place, including the paginated envelope details and the truncated check warning.

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, so the description appropriately covers the return envelope and pagination semantics. Combined with 100% schema parameter coverage and annotations, the description gives an agent everything needed to invoke and interpret this 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 100%, with each parameter already documented. The description reinforces the resource_kind filter but adds no new parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List resources in Aria Operations filtered by kind.' It differentiates itself from get_resource by explicitly saying 'Start here: this turns a name or kind into the UUID other resource tools need' and routing the agent to 'get_resource for detail on one row.'

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

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

The description gives clear usage context: it is the entry point for resolving a name or kind into a UUID for downstream resource tools, and it directs the agent to get_resource next. It does not enumerate exclusions relative to sibling tools, but the guidance is sufficiently directional for correct selection.

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

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

The description goes far beyond the annotations by explaining nuanced behaviors: sizing_status semantics, the reclaimable zero-value caveat, the none_published ambiguity, the difference from the vendor UI calculation, and the paginated envelope with truncation. These details prevent serious misinterpretation and are not inferable from readOnlyHint or idempotentHint.

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 every section earns its place: a one-line summary, metric source, usage pointer, critical sizing_status interpretation rules, a UI comparison warning, and return envelope details. It is front-loaded and uses bullets to keep the caveats scannable.

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 there is no output schema, the description fully compensates by explaining the return envelope fields and the need to check truncated. It also covers the three sizing_status states, how to obtain target VMs, and the API's limitations, making the tool safely callable in a standalone manner.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context around resource_id by pointing to list_resources for VM UUIDs and mentions pagination, which relates to limit, but it does not materially expand parameter semantics beyond what the schema already documents.

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

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

The opening line states a specific verb and resource: 'List VM rightsizing data — recommended CPU/memory/disk size per VM.' It further clarifies the exact metrics read and notes this is the only rightsizing signal the public API publishes, which distinguishes it from sibling tools that handle resources, alerts, or capacity.

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

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

The description gives clear context on when to use the tool: to compare recommendations against provisioned size, with UUIDs obtained from list_resources. It also provides explicit operational guidance around sizing_status and warns against treating the API output as matching the vendor UI's Rightsize page, though it does not explicitly enumerate exclusions such as 'use get_resource_metrics instead for raw metrics.'

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 signal readOnlyHint and idempotentHint, but the description adds substantial non-obvious behavior: the exact paginated envelope fields, the meaning of truncated, the 'rejected, not clamped' limit handling, and the explicit warning not to loop on truncated. This goes well beyond what annotations provide.

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

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

The purpose is front-loaded, and every subsequent sentence explains a nontrivial behavior needed to invoke the tool correctly. The pagination instructions are dense but not padded, and the warning about truncated earns its place.

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

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

For a paginated list tool with 5 optional parameters and no output schema, the description covers the return envelope, the pagination contract, and the edge-case caveat about truncated. It tells the agent what it will receive and how to iterate safely, so nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining how limit, offset, and next_offset interact: pages are walked by passing next_offset back, out-of-range limits are rejected, and next_offset being null signals the end. This clarifies parameter behavior beyond the schema descriptions.

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

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

The description opens with '[READ] List symptom definitions' and ties the tool to a concrete downstream use: 'use the returned IDs when calling create_alert_definition.' This clearly identifies the verb, resource, and purpose, and distinguishes 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?

It gives a clear use case for the tool by relating its IDs to create_alert_definition, and its read-only nature is reinforced. It does not explicitly compare against sibling tools like list_alert_definitions, but the purpose statement is enough to orient an agent without leaving the main scenario ambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description discloses a real-time latency profile, a hard prerequisite (VODAP integration) with the resulting actionable error, and the return envelope contents. It also surfaces a non-obvious gotcha: the sibling service base path is inferred and every result carries base_path_confirmed=False until validated. This is substantial 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?

The description is compact yet information-dense, with each sentence contributing a distinct fact: purpose, use case, prerequisite, return format, and a critical gotcha. The '[READ]' prefix and front-loaded purpose statement make the tool's intent immediately clear.

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 query tool with full schema coverage and no output schema, the description covers the essential operational context: when to use it, what it returns, the required integration, error behavior, and a latency caveat. An agent has enough information to select and invoke it correctly under normal conditions.

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

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

Schema description coverage is 100%, so the input schema and its per-property descriptions already document all five parameters thoroughly. The description adds high-level context about the query and return shape, but does not need to repeat parameter syntax; baseline 3 is appropriate.

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

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

The opening line, '[READ] Run a real-time PromQL instant query', states a specific verb, resource, and temporal characteristic. It also names the underlying VODAP service, separating it clearly from the historical-rollup tool get_resource_metrics among the 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 says to use this for near-real-time (~2s) metrics and references get_resource_metrics as the complementary historical alternative, giving clear context for tool selection. It does not spell out an explicit 'do not use when...' condition, though the complementing-rollups phrase implies the boundary.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavioral context: it labels the operation as [WRITE], explains that disabling is reversible while deleting is not, and states the return fields (definition_id, enabled, action taken). This goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no redundancy. The [WRITE] marker and primary action are front-loaded, and the alternative guidance is compact and directly actionable. Every sentence earns its place.

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

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

For a simple mutation tool with all parameters schema-documented and no output schema, the description covers the essential context: what it does, when to use it, what it returns, and how it differs from the destructive sibling. An agent has enough to select and call this 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 100%, so the baseline is 3. The description adds a small amount of semantic context by equating disabling with 'silencing' a definition, but it does not materially explain any parameter beyond what the schema already provides (definition_id from list_alert_definitions, enabled True/False).

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

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

The description clearly states a specific verb ('Enable or disable') and a specific resource ('an existing alert definition'), distinguishing it from sibling tools like delete_alert_definition and create_alert_definition. It leaves no ambiguity about what action the tool performs.

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 gives the condition for choosing this tool over delete_alert_definition: 'Use this instead of delete_alert_definition when you only want to silence a definition'. It also explains the rationale (reversible vs. irreversible), providing clear when-to-use guidance.

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